الانتقال إلى المحتوى الرئيسي

أدلة التكامل

إعداد خطوة بخطوة لـ champollion مع أُطر العمل الشائعة.

إعداد مفتاح API​

قبل التكامل مع أي إطار عمل، تحتاج إلى مفتاح API للترجمة. يدعم Champollion مزوّدَين اثنين:

الخيار أ: OpenRouter (موصى به)​

يوفّر OpenRouter واجهة API موحّدة لأكثر من 200 نموذج LLM. تتوفر فئة مجانية.

# Sign up at https://openrouter.ai, then:
export OPENROUTER_API_KEY=sk-or-v1-...

# Or add to .env.local:
OPENROUTER_API_KEY=sk-or-v1-your-key-here

الأنسب لـ: المشاريع الغنية بالمحتوى، وترجمة Markdown، والمشاريع التي تحتاج إلى حماية واعية بالمحتوى (كتل التعليمات البرمجية، والأكواد المختصرة، ومتغيرات الاستيفاء).

الخيار ب: Google Translate​

export GOOGLE_TRANSLATE_API_KEY=...

الأنسب لـ: أزواج السلاسل النصية من نوع مفتاح-قيمة عالية الحجم (أكثر من 130 لغة). غير موصى به لمحتوى Markdown — فـ Google Translate لا يدرك كتل التعليمات البرمجية أو الأكواد المختصرة أو متغيرات الاستيفاء.

لاستخدام Google Translate بشكل صريح:

champollion sync --method google-translate

نصيحة: إذا تم تعيين GOOGLE_TRANSLATE_API_KEY فقط (بدون مفتاح OpenRouter)، يتحوّل champollion تلقائيًا إلى Google Translate.

Hugo (TOML / YAML / Markdown)​

بنية المشروع​

يستخدم Hugo i18n/ لترجمات السلاسل النصية وcontent/ لمحتوى الصفحات:

my-hugo-site/
├── i18n/
│   ├── en.toml             ← source of truth
│   ├── fr.toml
│   └── ja.toml
├── content/
│   ├── posts/
│   │   ├── hello.md        ← source (English)
│   │   ├── hello.fr.md
│   │   └── hello.ja.md
│   └── about.md
└── .env.local

الإعداد​

npm install --save-dev champollion
# .env.local
OPENROUTER_API_KEY=sk-or-v1-your-key-here

أنشئ champollion.config.json:

{
  "version": 3,
  "inputLocale": "en",
  "localesDir": "./i18n",
  "contentDir": "./content",
  "format": "auto",
  "languages": ["fr", "de", "ja", "es", "ko", "zh"]
}
champollion sync           # sync i18n string files + content files
champollion sync --dry     # preview changes without writing

تفاصيل ترجمة المحتوى​

المقدمة الوصفية (Front matter): يدعم كلًّا من فواصل YAML (---) وTOML (+++). يترجم title وdescription وsummary وsubtitle وcaption وlinkTitle افتراضيًا. جميع الحقول الأخرى (date وdraft وtags وweight وslug وغيرها) يتم الحفاظ عليها. خصّصها باستخدام translatableFields في ملف الإعدادات الخاص بك.

حماية الكتل: كتل التعليمات البرمجية، والأكواد المختصرة الخاصة بـ Hugo ({{< >}}، {{% %}})، والتعليمات البرمجية المضمّنة، وHTML الخام تُحمى تلقائيًا باستخدام عناصر نائبة حارسة من Unicode. وتمرّ دون أي تعديل.

اصطلاح تسمية الملفات: يتّبع نمط الترجمة حسب اسم الملف في Hugo:

  • my-post.md → my-post.fr.md
  • my-post.en.md → my-post.fr.md (يحذف لاحقة اللغة المصدر)

تخطّي الموجود: لا تتم أبدًا الكتابة فوق الملفات المترجمة الموجودة. احذف الملف الهدف لإجبار إعادة الترجمة.

صيغ الجمع​

تدعم ملفات اللغات بصيغتي TOML وYAML صيغ الجمع وفق CLDR:

[items]
one = "{{ .Count }} item"
other = "{{ .Count }} items"

تُمثَّل داخليًا كـ items.one وitems.other لأغراض المقارنة، ثم يُعاد تسلسلها إلى التنسيق المقسّم الصحيح عند الكتابة.

next-intl (JSON)​

بنية المشروع​

my-app/
├── messages/
│   └── en.json        ← source of truth
├── src/
│   ├── i18n/
│   │   ├── routing.ts
│   │   └── request.ts
│   └── middleware.ts
└── .env.local

الإعداد​

npm install --save-dev champollion

أنشئ champollion.config.json:

{
  "version": 3,
  "inputLocale": "en",
  "localesDir": "./messages",
  "languages": ["fr", "de", "ja", "es", "ko", "zh", "pt", "ar"]
}
npx champollion sync

يُنشئ messages/fr.json وmessages/ja.json وغيرها — مترجمة بالكامل، مع الحفاظ على بنية المفاتيح المتداخلة لديك. يلتقطها next-intl تلقائيًا.

سير عمل التطوير​

{
  "scripts": {
    "dev": "champollion watch & next dev",
    "i18n:sync": "champollion sync",
    "i18n:audit": "champollion audit"
  }
}

react-i18next (JSON)​

بنية الملفات المسطّحة (موصى بها)​

locales/
├── en.json
├── fr.json
└── ja.json
{
  "version": 3,
  "inputLocale": "en",
  "localesDir": "./locales",
  "languages": ["fr", "de", "ja"]
}

بنية المجلدات المتداخلة​

إذا كنت تستخدم بنية {locale}/{namespace}.json، فأنشئ سكربت مزامنة للتسطيح ← الترجمة ← إلغاء التسطيح. راجع وثائق react-i18next لمزيد من التفاصيل.