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

كيف يعمل Sync

الأمر sync هو العملية الأساسية في champollion. إليك ما يحدث عند تشغيل npx champollion sync.

نظرة عامة على خط المعالجة​

خطوة بخطوة​

1. تحليل الإعدادات​

يقوم Champollion بتحميل champollion.config.json (أو يكتشف الإعدادات تلقائيًا). ويحدد:

  • اللغة المصدر واللغات الهدف
  • مخطط الأزواج (أي تركيبات مصدر←هدف ستتم معالجتها)
  • إعدادات الطريقة والنموذج والجودة لكل زوج

قبل فحص الملفات، يطبع champollion ترويسة بدء التشغيل:

champollion v0.1.0

[INFO] Detected format: json (auto)
[INFO] Detected framework: Hugo
  • شعار الإصدار: يعرض الإصدار المثبَّت لأغراض تصحيح الأخطاء وتقارير المشكلات.
  • اكتشاف التنسيق: يُبلغ عن تنسيق الملف وما إذا كان قد اكتُشف تلقائيًا (auto) أو تم تكوينه صراحةً (config). يدعم json وtoml وyaml.
  • اكتشاف إطار العمل: عند تعيين contentDir، يتعرف على إطار العمل (Hugo) لتأكيد أن مزامنة المحتوى نشطة.

2. فحص المصدر​

يتم تحميل ملف اللغة المصدر وتسطيحه إلى خريطة مفتاح←قيمة:

// Input (nested)
{ "hero": { "title": "Welcome", "subtitle": "Build" } }

// Flattened
{ "hero.title": "Welcome", "hero.subtitle": "Build" }

3. اكتشاف التغييرات​

يقرأ Champollion الملف .champollion.lock، الذي يخزّن تجزئات SHA-256 لقيم المصدر المترجمة سابقًا. ولكل مفتاح، يتحقق من:

الحالةالإجراء
المفتاح غير موجود في الهدفترجمة
تجزئة المصدر تغيّرت منذ آخر مزامنةإعادة ترجمة (قديم)
قيمة الهدف تبدأ بـ [EN]إعادة ترجمة (علامة احتياطية قديمة)
تجزئة المصدر لم تتغير والمفتاح موجودتخطٍّ

لهذا السبب يترجم champollion ما تغيّر فقط — فهو لا يعيد ترجمة ملفك بالكامل في كل مزامنة.

4. التجميع في دفعات​

تُجمَّع المفاتيح في دفعات (الافتراضي: 80 مفتاحًا/دفعة لطرق LLM، و128 لـ Google Translate). يقلل التجميع في دفعات من عدد طلبات API ذهابًا وإيابًا مع إبقاء المطالبات قابلة للإدارة.

أثناء الترجمة، يعرض champollion شريط تقدم سطريًا يتحدث بعد اكتمال كل دفعة:

[INFO] fr.json — 2,847 missing
     ████████████████░░░░░░░░░░░░░░░░ 1,440/2,847 keys

يُرسم الشريط باستخدام \r إرجاع المؤشر للتحديثات في المكان نفسه — دون تمرير. ويتم إخفاؤه في وضعَي --quiet و--json.

4ب. ذاكرة الترجمة​

قبل التجميع في دفعات، يتحقق champollion من ذاكرة التخزين المؤقت لذاكرة الترجمة (.champollion/tm.json). المفاتيح التي يتطابق نصها المصدر + اللغة + الطريقة مع ترجمة سابقة تُقدَّم فورًا من الذاكرة المؤقتة — دون الحاجة إلى استدعاء API.

  [TM] 142 key(s) served from cache
  Translating 3 key(s) to French (llm)... [OK]

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

لتجاوز الذاكرة المؤقتة لتشغيل واحد: champollion sync --no-tm

5. الترجمة​

تُرسل كل دفعة إلى طريقة الترجمة المكوَّنة:

  • llm: مطالبة منظمة إلى OpenRouter مع تعليمات حول مستوى اللغة وإرشادات الجنس اللغوي
  • llm-coached: مثل السابق، لكن مع حقن قواعد نحوية وقاموس وملاحظات أسلوبية
  • google-translate: طلب دفعة عبر Google Cloud Translation API v2
  • api: طلب HTTP POST إلى نقطة نهاية بعيدة

رسالة النظام (مستوى اللغة، إرشادات الجنس اللغوي، القواعد) متطابقة عبر الدفعات للغة معينة، مما يتيح التخزين المؤقت للمطالبات — حيث يقوم مزودون مثل Anthropic وGoogle بتخزين رسائل النظام المتكررة مؤقتًا، ما يقلل تكاليف الرموز (tokens).

6. بوابة الجودة​

تُتحقَّق من صحة كل ترجمة قبل كتابتها على القرص. تُنفَّذ خمسة فحوصات:

الفحصما يكتشفهمثال
فارغ/خالٍالنموذج لم يُرجع شيئًا""
صدى المصدرالنموذج أرجع المدخل الإنجليزي نفسه"Welcome" لليابانية
حلقة هلوسةثلاثيات متكررة"Qo' Qo' Qo' Qo'"
تضخّم الطولالمخرَج أطول من المصدر بمقدار 4 أضعاف أو أكثرمصدر من 10 أحرف ← مخرَج من 50 حرفًا
مطابقة نظام الكتابةنظام كتابة خاطئ للغةنص لاتيني للغة العربية

تُسجَّل حالات الفشل ببادئة [GATE]. لا توجد بدائل احتياطية صامتة.

راجع بوابة الجودة للتفاصيل.

6ب. التحقق من المصطلحات​

بالنسبة للأزواج الموجَّهة التي لديها قاموس، يتحقق champollion مما إذا كان نموذج LLM قد استخدم بالفعل المصطلحات المطلوبة بعد الترجمة. تُسجَّل المخالفات كتحذيرات [TERM]:

[TERM] en→fr: 2 term violation(s)
  • "dashboard" → expected "tableau de bord" but got "panneau"

هذه تحذيرات وليست أخطاء مانعة — تُكتب الترجمة على أي حال.

7. تسلسل إعادة المحاولة​

عند فشل تحليل JSON أو حدوث أخطاء على مستوى الدفعة، يعيد champollion المحاولة بدفعات أصغر تدريجيًا:

Full batch (80 keys) → Failed
  └→ Half batch (40 keys) → 1 failure
      └→ Individual keys (1 each) → Isolates the problem key

تُحدَّد ميزانية إعادة المحاولة بقيمة maxRetries (الافتراضي: 3) لمنع الإنفاق المفرط على الرموز (tokens).

8. الكتابة والقفل​

تُكتب الترجمات الناجحة في ملف اللغة الهدف، مع الحفاظ على بنية التداخل الأصلية. ويُحدَّث ملف القفل بتجزئات SHA-256 الجديدة.

9. التحقق​

بعد معالجة جميع الأزواج، يعيد champollion قراءة ملفات اللغات المكتوبة من القرص ويُجري عملية تحقق (ما لم يتم تعيين --no-verify). يكتشف هذا الفجوة بين الإبلاغ عن نجاح المزامنة ووجود مفاتيح خاطئة في الواقع:

  • تطابق المفاتيح — جميع مفاتيح المصدر موجودة في كل هدف
  • علامات [EN] الاحتياطية — علامات قديمة من عمليات تشغيل سابقة
  • ترجمات فارغة — قيم فارغة تسرّبت
  • مطابقة نظام الكتابة — لغات غير لاتينية بترجمات تحتوي على ASCII فقط
  • الحفاظ على العناصر النائبة — العناصر النائبة من نوع ICU تطابق المصدر
  • مشكلات الترميز — علامات BOM، أحرف غير مرئية

هذا متاح أيضًا كأمر مستقل champollion verify لبوابات CI.

ترجمة المحتوى (المرحلة 2)​

بالنسبة لمشاريع Docusaurus وHugo، يقوم sync بتشغيل مرحلة ثانية بعد ترجمة مفاتيح JSON. تترجم هذه المرحلة ملفات Markdown وMDX (التوثيق، منشورات المدونة، الدروس التعليمية) باستخدام الطرق وبوابة الجودة نفسها.

كيف تعمل​

  1. يكتشف Champollion جميع ملفات المحتوى المصدر (.md، .mdx) عبر اجتياز دليل content/docs
  2. لكل زوج ملف × لغة، يتحقق من ملف قفل محتوى منفصل (.champollion-content.lock) بحثًا عن تغييرات في تجزئات SHA-256
  3. تُجمَع الملفات المتغيرة أو المفقودة في مجموعة عناصر عمل مسطّحة
  4. تُعالَج المجموعة بتزامن متوازٍ (الافتراضي: 12 استدعاء API متزامنًا)
Phase 2: content (79 translations to process, 341 skipped, concurrency: 48)

    [1/79] (1%)  docs/concepts/security.md → ja [RE-TRANSLATE] (~3328s left)
    [2/79] (3%)  docs/concepts/security.md → th [RE-TRANSLATE] (~1821s left)
    ...
    [79/79] (100%) blog/v3-2-quality.md → de [OK]

  [OK] Created 79 content file(s), 341 unchanged

التوازي​

تعمل كل من المرحلة 1 (مفاتيح JSON) والمرحلة 2 (المحتوى) الآن بالتوازي:

  • المرحلة 1: تنطلق جميع ترجمات اللغات بشكل متزامن (الافتراضي: 50 لغة متزامنة). وداخل كل لغة، تعمل دفعات API أيضًا بالتوازي (4 دفعات متزامنة). مزامنة من 12 لغة تتضمن 120 مفتاحًا تكتمل في حوالي دقيقة واحدة بدلاً من حوالي 15 دقيقة.
  • المرحلة 2: تُترجَم جميع تركيبات ملف×لغة كمجموعة مسطّحة (الافتراضي: 12 استدعاء API متزامنًا). تُترجَم ملفات مختلفة ولغات مختلفة في الوقت نفسه.

تحكَّم في التوازي باستخدام --json-concurrency أو --content-concurrency أو --concurrency (يضبط كليهما):

# Faster JSON sync (more parallel locale translations)
npx champollion sync --json-concurrency 30

# Faster content sync (more parallel API calls)
npx champollion sync --content-concurrency 20

# Slower (gentler on rate limits)
npx champollion sync --concurrency 4

حماية المحتوى​

أثناء الترجمة، يحمي champollion المحتوى غير القابل للترجمة:

  • كتل التعليمات البرمجية (المسيّجة والمزاحة) تُستبدل بعناصر نائبة
  • حقول Frontmatter غير المدرجة في قائمة translatableFields تُحفظ كما هي
  • الروابط ومسارات الصور ووسوم HTML محمية
  • الأكواد المختصرة (Shortcodes) ومتغيرات الاستيفاء (مثل {count} و{{.Params.title}}) محمية

بعد الترجمة، تُستعاد جميع العناصر النائبة ويُتحقَّق من صحتها. إذا كان أي منها مفقودًا أو تالفًا، تُرفض الترجمة وتُعاد المحاولة.

النجاح الجزئي​

فشل دفعة واحدة لا يعطّل البقية. إذا نجحت 9 دفعات من أصل 10، تُكتب تلك الدفعات التسع. تُسجَّل الدفعة الفاشلة، ويمكنك إعادة تشغيل sync لإعادة المحاولة.

التشغيل التجريبي​

عاين ما سيتغير دون كتابة أي ملفات:

npx champollion sync --dry-run

إجبار إعادة الترجمة​

أجبِر مفاتيح معينة على إعادة الترجمة حتى لو لم تتغير:

npx champollion sync --force-keys "hero.title,nav.about"

تقدير التكلفة​

قبل الترجمة، يُنشئ champollion تقرير تكلفة ما قبل المزامنة يعرض التكاليف المقدَّرة لكل زوج. يعمل هذا تلقائيًا أثناء كل sync — تراه قبل إجراء أي استدعاءات API.

╔══════════════════════════════════════════════════════════╗
║  Cost Estimate                                          ║
╠════════════╦═══════╦════════════╦════════════════════════╣
║ Pair       ║ Keys  ║ Est. Cost  ║ Method                 ║
╠════════════╬═══════╬════════════╬════════════════════════╣
║ en → fr    ║   142 ║ $0.07      ║ google-translate       ║
║ en → ja    ║    38 ║   —        ║ llm (model-dependent)  ║
║ en → crk   ║    38 ║   —        ║ llm-coached            ║
╚════════════╩═══════╩════════════╩════════════════════════╝

ما الذي يُقدَّر​

توفر كل طريقة ترجمة تقدير التكلفة الخاص بها:

الطريقةأساس التكلفةالدقة
google-translateالسعر المعلن من Google (20 دولارًا/مليون حرف)دقيق
llmيختلف حسب نموذج OpenRouterيعتمد على النموذج — راجع أسعار OpenRouter
llm-coachedمثل llm بالإضافة إلى رموز سياق التوجيهيعتمد على النموذج
apiيحدده الخادمغير معروف — لا يمكن التقدير دون الاستعلام من نقطة النهاية

عندما يتعذر على طريقة ما تحديد التكلفة (طرق LLM، واجهات API البعيدة)، يُبلغ champollion عن — بدلاً من التخمين. استخدم --dry لرؤية تقديرات التكلفة دون الترجمة فعليًا.

انظر أيضًا​