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

البدء السريع

ترجم أول ملف لغة لديك خلال 60 ثانية.

1. إعداد ملفات اللغة​

أنشئ ملف لغة مصدريًا. يدعم Champollion صيغ JSON وTOML وYAML:

locales/en.json
{
  "hero": {
    "title": "Welcome to our platform",
    "subtitle": "Build something amazing"
  },
  "nav": {
    "home": "Home",
    "about": "About",
    "contact": "Contact"
  }
}

2. تعيين مفتاح API​

اختر مزوّد خدمة وعيّن المفتاح:

# Option A: OpenRouter (200+ models, recommended)
export OPENROUTER_API_KEY=sk-or-v1-...

# Option B: Gemini (free tier — zero cost to start)
export GEMINI_API_KEY=AI...

احصل على مفتاح Gemini مجاني من aistudio.google.com/apikey. واحصل على مفتاح OpenRouter من openrouter.ai.

3. تشغيل المزامنة​

npx champollion sync

:::tip Using Gemini? إذا اخترت الخيار B (Gemini)، أضف --method gemini:

npx champollion sync --method gemini

:::

سيقوم Champollion بما يلي:

  1. اكتشاف locales/en.json تلقائيًا كملف مصدر
  2. العثور على اللغات المستهدفة (أو طلب تحديدها)
  3. ترجمة جميع المفاتيح
  4. كتابة locales/fr.json وlocales/ja.json وغيرها
  5. إنشاء .champollion.lock لتتبّع ما تمت ترجمته

4. التحقق من النتائج​

cat locales/fr.json
{
  "hero": {
    "title": "Bienvenue sur notre plateforme",
    "subtitle": "Construisez quelque chose d'incroyable"
  },
  "nav": {
    "home": "Accueil",
    "about": "À propos",
    "contact": "Contact"
  }
}

ماذا يحدث بعد ذلك؟​

عند تغيير نص مصدري، يكتشف champollion التغيير عبر تتبّع تجزئة SHA-256 ويعيد ترجمة ذلك المفتاح فقط في المزامنة التالية:

locales/en.json (updated)
{
  "hero": {
    "title": "Welcome to Acme Platform",  // ← changed
    "subtitle": "Build something amazing"  // ← unchanged, skipped
  }
}
npx champollion sync
# Only "hero.title" is re-translated across all locales

يتم تقديم المفتاح غير المتغيّر (hero.subtitle) من ذاكرة التخزين المؤقت ذاكرة الترجمة في champollion — دون استدعاء API ودون تكلفة. تُبنى ذاكرة التخزين المؤقت تلقائيًا أثناء كل مزامنة وتُخزَّن في .champollion/tm.json.

اختياري: إنشاء ملف إعدادات​

لمزيد من التحكم، أنشئ ملف إعدادات:

npx champollion init                         # guided wizard
npx champollion init --yes --langs fr,de,ja  # quick setup with specific targets

يرشدك المعالج التفاعلي عبر إعدادات مستوى الخطاب المسبقة لكل لغة — وهي تعليمات جاهزة للنبرة ودرجة الرسمية مضبوطة وفقًا لنظامها اللغوي. تملك الفرنسية إعدادات T-V المسبقة (vouvoiement مقابل tutoiement)، وتملك الكورية مستويات خطاب (해요체 مقابل 합쇼체 مقابل 해체)، وتملك اليابانية خيارات keigo (です/ます مقابل 丁寧語).

أو أنشئ ملف إعدادات يدويًا باستخدام مفاتيح الإعدادات المسبقة:

champollion.config.json
{
  "version": 3,
  "inputLocale": "en",
  "localesDir": "./locales",
  "languages": {
    "fr": "casual-tu",
    "ko": "polite-haeyo",
    "ja": "polite"
  },
  "model": "google/gemini-2.5-flash"
}

شغّل npx champollion init لاستعراض الإعدادات المسبقة المتاحة لكل لغة.

اختياري: وضع المراقبة​

ترجم تلقائيًا عند تغيُّر ملفك المصدري:

npx champollion watch

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