CLI

استخدم @better-translate/cli عندما تريد من Better Translate بناء وتحديث ملفات اللغة نيابة عنك.

لا تحتاج إلى CLI لاستخدام حزم وقت التشغيل. إنه اختياري.

1. تثبيت الحزمة

npm install -D @better-translate/cli

يبقى CLI محايداً فيما يتعلق بمزود الخدمة. يقوم تطبيقك بتثبيت وتكوين حزمة مزود SDK للذكاء الاصطناعي مباشرة.

2. إنشاء ملف اللغة المصدر

أنشئ src/messages/en.json:

1{2  "home": {3    "title": "Hello",4    "description": "Welcome to the app"5  }6}

يمكنك أيضاً البداية بملف فارغ {} ودع bt extract يملأه.

3. إنشاء إعدادات CLI

أنشئ better-translate.config.ts:

1import { createOllama } from "ollama-ai-provider-v2";2import { defineConfig } from "@better-translate/cli/config";34const ollama = createOllama({5  baseURL: process.env.OLLAMA_BASE_URL ?? "http://localhost:11434/api",6});78export default defineConfig({9  sourceLocale: "en",10  locales: ["es", "fr"],11  model: ollama("qwen3:4b"),12  messages: {13    entry: "./src/messages/en.json",14  },15});

إذا كنت تستخدم Ollama، ثبّت ollama-ai-provider-v2. إذا كنت تستخدم مزوداً مستضافاً، ثبّت حزمة ذلك المزود بدلاً من ذلك، مثل @ai-sdk/openai أو @ai-sdk/anthropic أو @ai-sdk/moonshotai.

عنوان URL الافتراضي لـ Ollama API هو محلي: http://localhost:11434/api.

هذا يعمل بنفس الطريقة مع المزودين المستضافين مثل OpenAI وAnthropic وMoonshot AI. لم يعد CLI يتضمن مساعدي المزودين.

4. وضع علامة على السلاسل في الكود

بدلاً من تسمية مفاتيح الترجمة يدوياً، اكتب النص المصدر مباشرة وأضف { bt: true }:

1import { t } from "@better-translate/core";23export function navLabel() {4  return t("Home", { bt: true });5}

في وقت التشغيل، يُعيد { bt: true } السلسلة دون تغيير. سيستبدل CLI هذه المكالمات بمفاتيح مناسبة في الاستخراج التالي.

يمكنك أيضاً تمرير خيارات أخرى مثل params — يتم الاحتفاظ بها بعد الاستخراج:

1// ما تكتبه:2t("Hello world", { bt: true })3t("Hello {name}", { bt: true, params: { name: "" } })45// بعد أن يعيد bt extract كتابة الملف:6t("components.nav.helloWorld")7t("components.nav.helloName", { params: { name: "" } })

يأتي نطاق المفتاح من مسار الملف المصدر (components/nav.tsx → components.nav). يتم دائماً إزالة bt: true عند إعادة الكتابة.

5. استخراج مفاتيح المصدر

npx bt extract

يقوم هذا بفحص مكالمات t(..., { bt: true })، ويضيف المفاتيح المفقودة إلى ملف اللغة المصدر، ويعيد كتابة المكالمات إلى مفاتيح صارمة عادية.

يجد CLI تلقائياً better-translate.config.ts في جذر مشروعك. يُستخدم علم --config فقط إذا كان ملف الإعدادات في موقع مختلف.

6. تشغيل المولد

npx bt generate

يقوم هذا بإنشاء ملفات اللغة المستهدفة بجانب ملف المصدر.

إذا كان markdown.rootDir مُمكّناً وكان التشغيل سيُنشئ أو يستبدل ملفات .md أو .mdx مترجمة، يسأل CLI عن التأكيد قبل إجراء التغييرات. استخدم --yes أو -y لتخطي التأكيد:

npx bt generate --yes

يجب أن تمرر --yes في التشغيلات غير التفاعلية التي تحتاج إلى كتابة ملفات markdown مترجمة.

7. حذف المفاتيح غير المستخدمة

npx bt purge

يقوم هذا بفحص قاعدة الكود بحثاً عن مفاتيح الترجمة التي لم تعد مرجعاً لها في أي مكالمة t("...") ويحذفها من جميع ملفات اللغة. يطلب CLI تأكيداً لكل مفتاح على حدة قبل حذفه:

1? Purge unused key "home.oldTitle"? (y/N) y2? Purge unused key "sidebar.legacy"? (y/N) n

اكتب y لحذف المفتاح من جميع ملفات اللغة، أو n (أو Enter فقط) للاحتفاظ به.

لحذف جميع المفاتيح غير المستخدمة دفعة واحدة بدون تأكيد:

npx bt purge --yes

لمعاينة ما سيُحذف دون إجراء أي تغييرات:

npx bt purge --dry-run

المفاتيح الديناميكية: إذا كان كودك يستخدم مفتاحاً ديناميكياً مثل t(`section.${id}`)، لا يستطيع CLI تحليله بشكل ساكن. سيُحذّرك ويحمي المفاتيح التي تشترك في البادئة المكتشفة، أو يُعلّم المفتاح على أنه غير آمن ويتخطاه بدلاً من حذف شيء قد يكون لا يزال قيد الاستخدام بصمت.

8. استخدام الملفات المُنشأة في تطبيقك

بعد وجود الملفات، استوردها إلى إعدادات @better-translate/core الخاصة بك تماماً مثل أي ملف لغة مكتوب يدوياً.

Markdown

إذا كنت تريد أيضاً إنشاء markdown مُترجم، أضف خيار markdown.rootDir:

1import { createOllama } from "ollama-ai-provider-v2";2import { defineConfig } from "@better-translate/cli/config";34const ollama = createOllama({5  baseURL: process.env.OLLAMA_BASE_URL ?? "http://localhost:11434/api",6});78export default defineConfig({9  sourceLocale: "en",10  locales: ["es", "fr"],11  model: ollama("qwen3:4b"),12  messages: {13    entry: "./src/messages/en.json",14  },15  markdown: {16    rootDir: "./content/docs",17  },18});

مرجع الأوامر

Examples

أمثلة عملية كاملة متوفرة في GitHub repo:

• nextjs-example
• react-vite-example
• core-elysia-example