واجهة سطر الأوامر

استخدم @better-translate/cli عندما تريد أن يبني Better Translate ملفات الإعداد المحلي ويحدّثها نيابةً عنك.

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

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

npm install -D @better-translate/cli

تبقى واجهة سطر الأوامر محايدة للمزود. يثبّت تطبيقك ويضبط حزمة مزود AI SDK مباشرة.

2. إنشاء ملف الإعداد المحلي المصدر

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

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

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

3. إنشاء إعداد واجهة سطر الأوامر

أنشئ 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.

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

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

4. تعليم النصوص في الكود

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

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

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

يمكنك أيضًا تمرير خيارات أخرى مثل 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 })، ويضيف المفاتيح الناقصة إلى ملف الإعداد المحلي المصدر، ويعيد كتابة الاستدعاءات إلى مفاتيح صارمة عادية.

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

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

npx bt generate

ينشئ ملفات الإعداد المحلي المستهدفة بجانب ملف المصدر.

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

npx bt generate --yes

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

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

npx bt purge

يفحص قاعدة الشيفرة بحثًا عن مفاتيح ترجمة لم تعد مُشار إليها في أي استدعاء t("...") ويزيلها من جميع ملفات الإعداد المحلي. يطلب تأكيدًا لكل مفتاح قبل الإزالة:

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}`)، لا تستطيع واجهة سطر الأوامر حله ثابتًا. ستحذّرك، وتحمي أي مفاتيح تشترك في البادئة المكتشفة، أو تعلّم المفتاح غير آمن وتتخطاه بدل الحذف الصامت لشيء قد يكون ما زال مستخدمًا.

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});

مرجع الأوامر

أمثلة

أمثلة عمل كاملة في مستودع GitHub:

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