البدء السريع

تكمن القوة الأساسية لـ Lingo.dev CLI في القدرة على ترجمة التطبيقات ومحتوى ملفات Markdown إلى اللغات المستهدفة بكفاءة باستخدام أمر CLI واحد.

يفترض دليل البدء السريع هذا أنك إما على وشك جعل تطبيقك متعدد اللغات، أو قمت بالفعل بتكوينه للتعامل مع لغتين أو أكثر. لذلك، تم تصميم الدليل ليكون قصيرًا بما يكفي لإكماله في أقل من 10 دقائق، ولكنه مفصل بما يكفي لفهم الآليات الداخلية.

عند الانتهاء من هذا الدليل، ستتمكن من:

1. ترجمة محتوى التطبيق إلى الإسبانية واليابانية باستخدام محرك ترجمة الذكاء الاصطناعي؛
2. فهم كيفية عمل ملفات المصدر والملفات المستهدفة والتكوين معًا؛
3. إعداد سير عمل الترجمة الذي يمكن أن يوسع نطاق تطبيقك ومحتوى Markdown إلى عشرات اللغات وعشرات الآلاف من الكلمات.

لنبدأ!

المتطلبات الأساسية

Markdown

ملفات Markdown هي مستندات منظمة، مما يعني أنه لا يلزم إعداد مسبق. يقوم Lingo.dev CLI بمعالجة ملفات .md مباشرة، مع الحفاظ على التنسيق أثناء ترجمة المحتوى، لذا يمكنك المتابعة إلى الخطوة 1.

التطبيقات

لجعل التطبيق متعدد اللغات، تتطلب تطبيقات الويب والجوال الحديثة من المطورين إعداد تكوين التدويل (i18n) أولاً.

لهذا البدء السريع، سننشئ ملف JSON مستقل لتوضيح كيفية قيام Lingo.dev CLI بترجمة محتوى التطبيق.

عند التكامل مع تطبيقك الفعلي، اتبع أدلة الإطارات الموصى بها:

• React: react-intl
• Vue: vue-i18n
• Svelte: svelte-i18n
• Angular: ngx-translate
• iOS: Localizable.xcstrings
• Android: strings.xml

نظام ويندوز فقط: التشغيل عبر npx

إذا كنت تقوم بتشغيل npx للمرة الأولى، فإنه يتطلب Bash أو صدفة أخرى متوافقة. على نظام Windows، يمكنك تثبيت Git for Windows.

بعد التثبيت، وقبل تشغيل npx للمرة الأولى، قم بتعيين الصدفة لـ npx عن طريق تنفيذ أحد الأوامر التالية في الطرفية الخاصة بك (اعتمادًا على مكان تثبيت Git Bash):

npm config set script-shell "C:\\Program Files\\git\\bin\\bash.exe"

أو

npm config set script-shell "C:\\Program Files (x86)\\git\\bin\\bash.exe"

هذا مطلوب لتنفيذ حزمة lingo.dev بشكل صحيح على نظام Windows.

الخطوة 1. تهيئة المشروع

تستخدم واجهة سطر أوامر Lingo.dev ملف التكوين القياسي i18n.json للإعلان عن إعدادات التوطين الخاصة بك. لإنشائه بشكل تفاعلي، قم بتشغيل:

npx lingo.dev@latest init

سيطرح عليك أسئلة حول مشروعك، ثم ينشئ ملف i18n.json في جذر المشروع الخاص بك.

يجب أن يبدو الملف كما يلي:

{
  "locale": {
    "source": "en",
    "targets": ["es", "ja"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"]
    }
  }
}

دعنا نفكك كل عنصر من عناصر التكوين:

• locale.source — اللغة التي يكتب بها فريقك. يحدد هذا الإعداد الملفات التي تحتوي على المحتوى الموثوق. تتدفق جميع عمليات التوطين من المصدر إلى الأهداف.

• locale.targets — مصفوفة من رموز اللغات ISO 639-1 التي تمثل أسواقك المستهدفة. يتوافق كل رمز مع ملف منفصل (أو قسم داخل ملف، حسب التنسيق). يمكنك البدء بلغة أو لغتين وإضافة المزيد مع التوسع.

• buckets.json.include — أنماط شبيهة بـ Glob تخبر واجهة سطر الأوامر أين تجد وتنشئ ملفات اللغة. يتوسع الرمز المميز الخاص [locale] إلى كل رمز لغة. باستخدام النمط locales/[locale].json، تبحث واجهة سطر الأوامر عن locales/en.json كمصدر وتنشئ locales/es.json و locales/ja.json كأهداف. يمكنك تحديد أنماط متعددة وحتى مزج التنسيقات ضمن تكوين واحد.

الميزات المتقدمة التي ستكتشفها مع نمو مشروعك:

• حاويات متعددة لأنواع ملفات مختلفة أو أقسام من تطبيقك
• أنماط exclude لتخطي ملفات معينة
• lockedKeys لمنع ترجمة قيم محددة

إنشاء ملف المصدر باللغة الإنجليزية

لهذا البدء السريع، سننشئ ملف لغة:

mkdir -p locales
echo '{"greeting":"Hello, world!","button.submit":"Submit"}' > locales/en.json

هذا ينشئ دليل locales وملف مصدر باللغة الإنجليزية يحتوي على مفتاحين للترجمة. تعمل المفاتيح مثل greeting للهياكل المسطحة، بينما تساعد المفاتيح ذات المساحات الاسمية مثل button.submit في تنظيم التطبيقات الأكبر حجمًا.

الكائنات المتداخلة مدعومة أيضًا. ستجد المزيد من التفاصيل حول تنسيقات الملفات المختلفة في بقية الوثائق.

الخطوة 2. المصادقة

يرسل واجهة سطر أوامر Lingo.dev المحتوى الخاص بك إلى محرك الترجمة بالذكاء الاصطناعي للتوطين، لذلك نحتاج إلى المصادقة أولاً.

الخيار 1. الوصول المباشر إلى واجهة برمجة تطبيقات LLM

تساعدك واجهة سطر أوامر Lingo.dev على استخدام نماذج LLM مثل OpenAI أو Anthropic للتوطين والترجمة.

هذا يعني أنه يتم محاسبتك لكل رمز تمت معالجته، وتتحكم في اختيار النموذج، ومطالبات النظام، وجميع معلمات النموذج.

للمصادقة، قم بإنشاء ملف .env في جذر مشروعك باستخدام مفتاح API الخاص بك:

# إذا كنت تستخدم OpenAI

OPENAI_API_KEY=sk-...

# إذا كنت تستخدم Anthropic

ANTHROPIC_API_KEY=sk-...

بدلاً من ذلك، بدلاً من استخدام .env، يمكنك تصدير المتغير في جلسة الشل الحالية:

export ANTHROPIC_API_KEY=sk-ant-...

هل تريد إضافة دعم لمزود آخر؟ واجهة سطر أوامر Lingo.dev مفتوحة المصدر وترحب بالمساهمات! قم بعمل fork للمستودع وإرسال طلب سحب: github.com/lingodotdev/lingo.dev.

الخيار 2. محرك Lingo.dev

بدلاً من ذلك، يمكنك إنشاء حساب مجاني في محرك Lingo.dev واستخدامه كمحرك الترجمة بالذكاء الاصطناعي.

يوفر اختيار نموذج ديناميكي، وتوجيه تلقائي إلى نماذج مختلفة لكل زوج من اللغات، وبدائل نموذج تلقائية، وذاكرة ترجمة تأخذ في الاعتبار الترجمات السابقة، ودعم المصطلحات لمصطلحات المجال المحددة لمشروعك. هناك خيارات مجانية ومدفوعة، ويجب أن تكون الفئة المجانية Hobby كافية لهذا البرنامج التعليمي.

للمصادقة، قم بتشغيل:

npx lingo.dev@latest login

تفاصيل مهمة. إذا كنت تستخدم متصفح Brave، أو كانت إضافات المتصفح الخاصة بك تمنع تدفق المصادقة، يمكنك المصادقة يدويًا عن طريق إضافة متغير بيئة LINGODOTDEV_API_KEY إلى ملف .env الخاص بك:

LINGODOTDEV_API_KEY=...

ستجد الرمز المميز في إعدادات مشروع محرك Lingo.dev.

الخطوة 3. إعداد محرك الترجمة بالذكاء الاصطناعي

بعد إتمام عملية المصادقة، تحتاج إلى تكوين محرك الترجمة بالذكاء الاصطناعي الذي ستستخدمه.

الخيار 1. الوصول المباشر إلى واجهة برمجة تطبيقات LLM

لاستخدام OpenAI، قم بتحديث ملف التكوين i18n.json لاستخدام مزود openai:

{
  "locale": {
    "source": "en",
    "targets": ["es", "ja"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"]
    }
  },
  "provider": {
    "id": "openai",
    "model": "gpt-4o-mini",
    "prompt": "Act as a professional software localization expert. Translate each key from {source} to {target}. Preserve ICU message format placeholders like {name} and {{count}}. Maintain Markdown formatting including links and code blocks. Match the tone and formality of the source text. Technical terms that are typically untranslated in the industry should remain in English."
  }
}

يمكنك تجربة توجيهات مختلفة لتخصيص سلوك الترجمة، لكننا وجدنا أن هذا التوجيه يعتبر نقطة بداية جيدة!

تتحكم تكوينات provider في الوصول المباشر إلى نماذج اللغة الكبيرة (LLM):

• id — إما openai أو anthropic
• model — إصدار النموذج المحدد للاستخدام. أمثلة: gpt-4o-mini، gpt-4o (OpenAI)، أو claude-3-haiku، claude-3-sonnet (Anthropic).
• prompt — توجيه النظام الذي يرشد سلوك الترجمة. يتم استبدال العناصر النائبة {source} و{target} برموز اللغة الفعلية في وقت التشغيل. هذا التوجيه هو فرصتك لفرض المصطلحات والأسلوب والقواعد الخاصة بالمجال.

الخيار 2. محرك Lingo.dev

إذا كنت تستخدم محرك Lingo.dev كمحرك الترجمة بالذكاء الاصطناعي، يمكنك تخطي عقدة provider تمامًا.

يقوم المحرك تلقائيًا باختيار النماذج والتوجيهات بناءً على أبحاث فريق Lingo.dev وإعدادات المحرك الخاص بك.

تكوين ملف i18n.json الخاص بك:

{
  "locale": {
    "source": "en",
    "targets": ["es", "ja"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"]
    }
  }
}

ملاحظة: عند استخدام محرك Lingo.dev، احذف عقدة provider تمامًا. يقوم المحرك تلقائيًا باختيار النماذج والتوجيهات.

الخطوة 4. الترجمة

لتعريب تطبيقك، قم بتشغيل:

npx lingo.dev@latest i18n

ستقوم واجهة سطر الأوامر بإنشاء الملفات المستهدفة، وتحديث ملف i18n.lock الذي يتتبع بصمات المحتوى. هذا يضمن التحديثات التدريجية في عمليات التشغيل اللاحقة.

لقد قمت الآن بتعريب محتوى تطبيقك!

الخطوات التالية

لقد أكملت سير عمل التعريب الأساسي. يحتوي مستودعك الآن على ملفات معربة يمكن الالتزام بها ومراجعتها ونشرها مثل أي عنصر برمجي آخر.

من هنا، يمكنك:

• أتمتة سير العمل: تكامل CI/CD — قم بإعداد تكامل CI/CD للتعريب مع كل عملية دفع، والالتزام بالتغييرات تلقائيًا إلى مستودعك، عبر طلبات السحب أو الالتزامات المباشرة؛
• فهم الآليات الداخلية: كيف يعمل — تعرف على الخوارزميات وتحسينات الأداء والقرارات المعمارية.