CLI

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

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

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

npm install -D @better-translate/cli

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

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

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

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  providerOptions: {13    ollama: {14      think: true,15    },16  },17  messages: {18    entry: "./src/messages/en.json",19  },20});

إذا كنت تستخدم 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. استخدام الملفات المُنشأة في تطبيقك

بعد وجود الملفات، استوردها إلى إعدادات @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:

CLI