البدء السريع

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

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

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

ترجمة محتوى التطبيق إلى الإسبانية واليابانية باستخدام محرك ترجمة الذكاء الاصطناعي؛
فهم كيفية عمل ملفات المصدر والملفات المستهدفة والتكوين معًا؛
إعداد سير عمل الترجمة الذي يمكن أن يوسع نطاق تطبيقك ومحتوى 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

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

يستخدم Lingo.dev CLI ملف التكوين القياسي 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 تخبر CLI أين يجد وينشئ ملفات اللغة. يتوسع الرمز المميز الخاص [locale] إلى كل رمز لغة. باستخدام النمط locales/[locale].json، يبحث CLI عن 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 في جذر مشروعك مع مفتاح واجهة برمجة التطبيقات الخاص بك:


# إذا كنت تستخدم 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_TOKEN إلى ملف .env الخاص بك:

LINGODOTDEV_API_TOKEN=...

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

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

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

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

لاستخدام 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 في الوصول المباشر إلى نماذج اللغة الكبيرة:

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 للترجمة مع كل عملية دفع، والالتزام بالتغييرات تلقائيًا إلى المستودع الخاص بك، عبر طلبات السحب أو الالتزامات المباشرة؛
فهم الآليات الداخلية: كيف يعمل — تعرف على الخوارزميات وتحسينات الأداء والقرارات المعمارية.