CLI

Preview

@verbumia/cli

A small, scriptable CLI for everything you'd otherwise click through the dashboard: bootstrap a project, push and pull translations, gate CI on remote drift, peek at the missing-key queue. MIT-licensed, distributed via npm and Homebrew.

Preview · CLI قيد التطوير. قد تتغير الأوامر والإعدادات قبل 1.0 — انظر التغييرات القادمة المعلومة أسفل هذه الصفحة. الأوامر التسعة ووسائطها مؤكدة لـ V1، لكن صيغة الـ wire قد تتطور.

Install

Requires Node 20 LTS or newer. Two binaries get installed: verbumia and the shorter alias vrb — interchangeable.

طرفية Tap يُنشر مع V1

1# ثبّت عالمياً مرة واحدة — bin "verbumia" مع الاسم المختصر "vrb"2npm i -g @verbumia/cli 4# أو استخدمها دون تثبيت5npx @verbumia/cli@latest <command> 7# Homebrew tap يُنشر مع إطلاق V18brew install verbumia/tap/verbumia-cli

المصادقة

احصل على مفتاح API من Org Settings → API Keys → Create في لوحة التحكم (يُعرض السر مرة واحدة فقط؛ انسخ السلسلة الكاملة vrb_live_<prefix>.<secret>). استخدم النطاق project:read لـ status / pull / missing / projects، والنطاق project:write لـ push.

تفاعلي

1verbumia login2? الصق مفتاح API من Org Settings → API Keys (الإدخال مُخفى):3vrb_live_••••••••••••••••.•••••••••••••••••••••4✓ تم التحقق عبر GET /v1/auth/me — marc@example.com (org: acme).5✓ حُفظ في ~/.verbumia/credentials (chmod 600).

CI / غير تفاعلي

1# CI / غير تفاعلي — متغير البيئة يتقدم على الملف لكنه أضعف من --token2export VERBUMIA_TOKEN=vrb_live_<prefix>.<secret>3verbumia push

ترتيب الأولويات هو الراية --token ← متغير البيئة VERBUMIA_TOKEN ← ~/.verbumia/credentials. ملف credentials بصيغة JSON على شكل {"default":"<token>","<host>":"<token>"} ليتيح لك الاحتفاظ بمفاتيح منفصلة لـ prod / staging / نسخة self-hosted على نفس الجهاز.

اضبط مشروعك

شغّل verbumia init داخل المستودع لإنشاء verbumia.config.json في الجذر، أو اكتبه يدوياً. يكتشف الـ CLI أيضاً verbumia.config.{ts,js,toml,yml} تلقائياً إن فضّلت أحد هذه الصيغ.

verbumia.config.json

1// verbumia.config.json — في جذر المشروع2// يُكتشف تلقائياً أيضاً: verbumia.config.{ts,js,toml,yml}3{4  "project_uuid": "<project_uuid>",5  "source_language": "en",6  "locales": ["en", "fr-CA", "es", "ja"],7  "namespaces": ["common", "checkout"],8  "format": "json-i18next",9  "push": {10    "source_dir": "./src/locales",11    "file_pattern": "{locale}/{namespace}.json",12    "on_missing_namespace": "create"13  },14  "pull": {15    "dest_dir": "./src/locales",16    "file_pattern": "{locale}/{namespace}.json",17    "format": "json-i18next"18  },19  "missing_handler": {20    "endpoint": "https://api.verbumia.ca/v1/missing",21    "enabled_for_envs": ["dev", "staging"]22  }23}

مرجع الحقول

الحقل	النوع	الافتراضي / ملاحظة
project_uuid	string	— required
source_language	string	"en"
locales	string[] \| null	null = all
namespaces	string[] \| null	null = all
format	string	"json-i18next" \| "xliff" \| "json-flat"
push.source_dir	string	"./src/locales"
push.file_pattern	string	"{locale}/{namespace}.json"
push.on_missing_namespace	"create" \| "error"	"create"
pull.*	object	mirrors push.* (read path)
missing_handler	object	{ endpoint, enabled_for_envs }

الأوامر

يقبل كل أمر --config <path> للإشارة إلى ملف إعداد غير افتراضي، و--token <vrb_live_…> لتجاوز المصادقة المحلولة، و--json لإخراج قابل للقراءة آلياً.

verbumia init ينشئ verbumia.config.json في المجلد الحالي عبر سؤالك تفاعلياً عن project_uuid ولغة المصدر والصيغة.

الرايات

--project <uuid> عبئ project_uuid مسبقاً
--source-language <code> BCP-47 (افتراضياً "en")
--format <fmt> json | xliff

مثال

verbumia init --project <uuid>

verbumia login إدخال تفاعلي لمفتاح API. يتحقق الـ CLI من المفتاح عبر GET /v1/auth/me ثم يكتبه في ~/.verbumia/credentials بنمط 600.

الرايات

--token <vrb_live_…> مرّر المفتاح inline (يتجاوز السؤال؛ مفيد للسكربتات)

مثال

verbumia login

verbumia logout يمسح ~/.verbumia/credentials. لا يلغي المفتاح من جهة الخادم — لذلك استخدم لوحة التحكم.

الرايات

لا توجد رايات خاصة بهذا الأمر. استخدم الرايات العامة الموصوفة أعلاه.

مثال

verbumia logout

verbumia whoami يطبع org المفتاح النشط، وارتباطه بالمشروع، والنطاقات الممنوحة. طريقة سريعة لتشخيص مفاجآت «الحساب الخطأ».

الرايات

لا توجد رايات خاصة بهذا الأمر. استخدم الرايات العامة الموصوفة أعلاه.

مثال

verbumia whoami

verbumia projects يدرج المشاريع التي يستطيع المفتاح النشط الوصول إليها.

الرايات

--json إخراج قابل للقراءة آلياً (الافتراضي جدول TTY)

مثال

verbumia projects --json

verbumia status diff للقراءة فقط بين الملفات المحلية والمشروع البعيد — added / removed / changed لكل لغة وnamespace. بدون كتابة.

الرايات

--locale <code> ضيّق إلى لغة واحدة
--namespace <slug> ضيّق إلى namespace واحد

مثال

verbumia status --locale fr-CA

verbumia push يرفع ملفات i18n المحلية إلى Verbumia: ينشئ مفاتيح جديدة، يحدّث القيم المتغيّرة، ويتصرف وفق سياسة on-missing-key حين يُشار إلى مفتاح غير موجود في الخادم.

الرايات

--locale <code> ادفع هذه اللغة فقط
--namespace <slug> ادفع هذا الـ namespace فقط
--dry-run أظهر الخطة دون التطبيق
--on-missing-key <create|skip> ما الذي يحدث حين يشير الملف المحلي إلى مفتاح غير موجود في الخادم

مثال

verbumia push --dry-run

verbumia pull ينزّل الترجمات البعيدة إلى pull.dest_dir المضبوط — ذرّياً لكل ملف. يقوم أيضاً بدور مسار «export»: مرّر --format للتحويل عند الإخراج.

الرايات

--locale <code> اسحب هذه اللغة فقط
--namespace <slug> اسحب هذا الـ namespace فقط
--format <fmt> json | xliff (يتجاوز config.format لهذه التشغيلة)

مثال

verbumia pull --format xliff

verbumia missing يدرج أحداث المفاتيح الناقصة المعلّقة التي يلتقطها SDK في الـ runtime. للقراءة فقط — مفيد للتصنيف من الطرفية دون فتح لوحة التحكم.

الرايات

--locale <code> تصفية حسب اللغة
--since <iso> الأحداث الأحدث من ختم زمني ISO-8601 فقط
--limit <n> أقصى عدد صفوف (افتراضياً 20)

مثال

verbumia missing --locale ja --limit 50

لا يوجد أمر export منفصل — يغطّيه pull --format. سيصل import من Lokalise / Crowdin / Phrase بعد V1 حين تتوفر نقاط الـ backend المقابلة؛ في الوقت الحالي، ضع ملف JSON أو XLIFF في push.source_dir ثم شغّل verbumia push.

تكامل CI

شغّل verbumia status --json في كل PR. الخروج بقيمة غير صفرية عند وجود انجراف يمنحك بوّابة رخيصة بنمط «هل أرسل أحدهم مفتاحاً دون إخبار i18n؟».

.github/workflows/i18n.yml

1# .github/workflows/i18n.yml — حجب البناء عند انجراف الـ remote2name: i18n status3on: { pull_request: { branches: [main] } }4jobs:5  status:6    runs-on: ubuntu-latest7    steps:8      - uses: actions/checkout@v49      - uses: actions/setup-node@v410        with: { node-version: 20 }11      - run: npx -y @verbumia/cli status --json12        env:13          VERBUMIA_TOKEN: ${{ secrets.VERBUMIA_TOKEN }}

تغييرات كاسرة قادمة معلومة

مثبّتة من باب الشفافية. كل واحد منها يصل في إصدار minor مع نافذة deprecation بطول إصدار واحد — ابقَ على أحدث @verbumia/cli وسترى التحذير قبل الكسر.

V1.1 — ينقسم config.format إلى { input, output } ليتمكن push وpull من استخدام صيغ مختلفة.
V1.1 — يصبح push --on-missing-key كائن سياسة (متعدّد الحالات) بدلاً من enum بقيمتين.
V1.1 — تُعاد تسمية سلسلة الصيغة "json-flat" إلى "flat-json" لاتساق التسمية.