الإعدادات

يعمل Champollion بدون أي إعدادات مسبقة — فهو يكتشف تلقائيًا ملفات اللغات (locale files) وصيغتها واللغات المستهدفة من مشروعك. لمزيد من التحكم، أنشئ champollion.config.json في جذر مشروعك، أو نفّذ:

npx champollion init

المرجع الكامل للإعدادات

champollion.config.json

{
  "version": 3,
  "inputLocale": "en",
  "localesDir": "./locales",
  "contentDir": null,
  "translatableFields": null,
  "format": "auto",
  "model": "google/gemini-3.5-flash",
  "temperature": 0.3,
  "defaultMethod": "llm",
  "batchSize": 80,
  "coachingFile": null,
  "promptContext": null,
  "jsonConcurrency": 200,
  "contentConcurrency": 48,
  "fallbackPrefix": "[EN] ",
  "apiKeyEnvVar": "OPENROUTER_API_KEY",
  "baseUrl": "",
  "pairs": {},
  "languages": {},
  "lint": {
    "srcDir": null,
    "ignore": ["node_modules", ".next", "dist"],
    "minLength": 2
  },
  "seo": {
    "urlPattern": "/:locale/:path",
    "pages": null
  },
  "typegen": {
    "output": null,
    "autoGenerate": false
  }
}

:::note لم يتم تنفيذ typegen بعد يتعرف محمّل الإعدادات على كتلة الإعدادات typegen ويحافظ عليها، لكن توليد أنواع TypeScript لم يُنفَّذ بعد. هذه الكتلة مجرد عنصر نائب لميزة مخطط لها. تعيين هذه القيم ليس له أي تأثير. :::

الحقول

الحقل	النوع	القيمة الافتراضية	الوصف
version	number	3	إصدار مخطط الإعدادات. دائمًا 3.
inputLocale	string	"en"	رمز اللغة المصدر (BCP 47).
localesDir	string	"./locales"	مسار ملفات اللغات. يفحص Champollion هذا المجلد.
contentDir	string	null	مجلد محتوى Hugo. يفعّل ترجمة نصوص Markdown.
translatableFields	string[]	null	تجاوز حقول الـ frontmatter الافتراضية القابلة للترجمة في ترجمة المحتوى. null يستخدم القيم الافتراضية المدمجة (title، description، summary).
format	string	"auto"	صيغة الملف: json أو toml أو yaml أو auto (الكشف من الامتداد).
model	string	"google/gemini-3.5-flash"	النموذج الافتراضي لطرق LLM. يقبل معرّفات OpenRouter الكاملة (provider/model) أو الأسماء المختصرة من shared/model-aliases.json (مثل gemini-flash). يستخدم المزودون المباشرون أسماء مجردة (مثل gpt-4o).
temperature	number	0.3	درجة حرارة نموذج LLM ‏(0.0–2.0). كلما انخفضت القيمة، زادت الحتمية.
defaultMethod	string	"llm"	طريقة الترجمة الافتراضية: llm، llm-coached، google-translate، deepl، microsoft-translator، libretranslate، openai، anthropic، gemini، api. تتجاوزها راية سطر الأوامر --method.
batchSize	number	80	عدد المفاتيح في كل دفعة ترجمة. القيمة الأعلى = استدعاءات API أقل، لكن مطالبات (prompts) أكبر.
coachingFile	string	null	مسار ملف نصي حر يحتوي على مطالبة توجيهية (نسبيًا إلى جذر المشروع). تُقرأ المحتويات عند بدء التشغيل وتُحقَن في مطالبة النظام داخل كتلة Coaching guidance:.
promptContext	string	null	نص يصف سياق التطبيق ويُحقَن في مطالبة النظام (مثل "أوصاف منتجات تجارة إلكترونية"). يساعد النموذج على تكييف الترجمات مع مجالك.
jsonConcurrency	number	200	الحد الأقصى لترجمات اللغات المتوازية في مزامنة مفاتيح JSON. تتجاوزه راية سطر الأوامر --json-concurrency.
contentConcurrency	number	48	الحد الأقصى لاستدعاءات API المتوازية لترجمة المحتوى (Markdown/MDX). تتجاوزه راية سطر الأوامر --content-concurrency.
fallbackPrefix	string	"[EN] "	بادئة علامة تستخدمها audit وverify للكشف عن القيم القديمة غير المترجمة من عمليات تشغيل سابقة. لا يكتب Champollion هذه البادئة — بل يقرؤها فقط لأغراض الكشف.
apiKeyEnvVar	string	"OPENROUTER_API_KEY"	اسم متغير البيئة الخاص بمفتاح API. يمكن تجاوزه لاستخدام أسماء متغيرات بيئة مخصصة.
baseUrl	string	""	الرابط الأساسي لتوليد عناصر SEO ‏(hreflang، خرائط المواقع، JSON-LD).
pairs	object	{}	تجاوزات الطريقة والنموذج والجودة لكل زوج لغوي. راجع إعدادات الأزواج.
languages	object	{}	تجاوزات لكل لغة. راجع إعدادات اللغات.
lint.srcDir	string	null	مجلد المصدر لفحص lint. null = الكشف التلقائي من إطار العمل.
lint.ignore	string[]	["node_modules", ...]	أنماط glob لاستثنائها من lint.
lint.minLength	number	2	الحد الأدنى لطول النص لتمييزه كنص مضمَّن (hardcoded).
seo.urlPattern	string	"/:locale/:path"	قالب نمط الروابط لتوليد وسوم hreflang.
seo.pages	string[]	null	قائمة صفحات صريحة لـ SEO. null = الكشف التلقائي من مفاتيح اللغات.
typegen.output	string	null	مسار الإخراج لأنواع TypeScript المولَّدة. null = معطّل.
typegen.autoGenerate	boolean	false	إعادة توليد الأنواع تلقائيًا بعد كل مزامنة.

إعدادات الأزواج

يمكن إعداد كل زوج مصدر→هدف بشكل مستقل:

{
  "pairs": {
    "en:fr": {
      "method": "google-translate",
      "qualityTier": "high"
    },
    "en:ja": {
      "method": "llm",
      "model": "google/gemini-2.5-pro"
    },
    "en:crk": {
      "methodPlugin": "crk-coached-v1"
    }
  }
}

حقول الأزواج

الحقل	النوع	الوصف
method	string	طريقة الترجمة: llm، llm-coached، google-translate، deepl، microsoft-translator، libretranslate، openai، anthropic، gemini، api
methodPlugin	string	اسم إضافة مثبّتة (من .champollion/methods/)
model	string	تجاوز النموذج الافتراضي لهذا الزوج
temperature	number	تجاوز درجة الحرارة الافتراضية لهذا الزوج
batchSize	number	تجاوز حجم الدفعة الافتراضي لهذا الزوج
register	string	تجاوز مستوى الأسلوب/النبرة (مفتاح إعداد مسبق أو نص حر)
endpoint	string	رابط نقطة نهاية API البعيدة. مطلوب عندما يكون method هو api.
coachingFile	string	مسار ملف مطالبة توجيهية لهذا الزوج
promptContext	string	سياق التطبيق لهذا الزوج
qualityTier	string	مستوى العرض: standard، high، research، verified

إعدادات اللغات

تقبل اللغات ثلاث صيغ:

مصفوفة من الرموز (الأبسط)

{
  "languages": ["fr", "de", "ja"]
}

تحصل كل لغة على مستوى الأسلوب الافتراضي الخاص بها من جدول الأساليب المدمج. اللغات التي ليس لها قيمة افتراضية تحصل على "Professional register.".

كائن مع نصوص أسلوب

يمكن أن تكون القيمة مفتاح إعداد مسبق من بطاقة اللغة، أو نص أسلوب مخصص:

{
  "languages": {
    "fr": "casual-tu",
    "ko": "formal-hapsyo",
    "ja": "Custom: Polite Japanese for a gaming app."
  }
}

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

كائن مع إعدادات كاملة

{
  "languages": {
    "crk": {
      "name": "Plains Cree",
      "register": "SRO syllabics with grammatical precision.",
      "model": "google/gemini-2.5-pro",
      "batchSize": 5,
      "maxRetries": 5,
      "script": "cans"
    }
  }
}

يمكنك المزج بين الصيغة المختصرة والكائنات الكاملة في الكتلة نفسها.

حقول اللغات

الحقل	النوع	الوصف
register	string	تعليمات الأسلوب/النبرة. يمكن أن تكون مفتاح إعداد مسبق (مثل casual-tu أو formal-hapsyo) أو نصًا مخصصًا. راجع بطاقات اللغات.
name	string	اسم اللغة بصيغة مقروءة (لعرض الحالة)
model	string	تجاوز النموذج الافتراضي
temperature	number	تجاوز درجة الحرارة الافتراضية
batchSize	number	تجاوز حجم الدفعة الافتراضي
coachingFile	string	مسار ملف مطالبة توجيهية لهذه اللغة
promptContext	string	سياق التطبيق لهذه اللغة
maxRetries	number	الحد الأقصى لمحاولات إعادة المحاولة للدفعات الفاشلة (الافتراضي: 3)
script	string	رمز نظام الكتابة وفق ISO 15924. يفعّل التحقق من نظام الكتابة في بوابة الجودة.

:::info سلسلة الوراثة تُحَل الإعدادات بهذا الترتيب (الأول يفوز):

مستوى الزوج ← مستوى اللغة ← الإعدادات العامة ← القيم الافتراضية

على سبيل المثال، إذا عيّن pairs["en:fr"] القيمة model، فإنها تتجاوز قيمتي model على مستوى اللغة وعلى المستوى العام معًا. :::

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

إذا لم تكن لغتك المصدر هي الإنجليزية:

# CLI flag (one-time)
npx champollion sync --source fr

champollion.config.json (permanent)

{
  "inputLocale": "fr"
}

ملف القفل

ينشئ Champollion .champollion.lock لتتبع تجزئات SHA-256 لقيم المصدر المترجمة. قم بإيداع هذا الملف (commit) حتى يتشارك جميع المطورين خط الأساس نفسه للترجمة.

عندما تتغير قيمة في المصدر، لا تعود التجزئة متطابقة، فيعيد champollion ترجمة ذلك المفتاح في المزامنة التالية.

.champollionignore

أنشئ .champollionignore في جذر مشروعك لاستثناء ملفات من فحص lint. يستخدم أنماط glob، مثل .gitignore:

.champollionignore

src/components/legacy/**
src/utils/constants.js
**/*.test.js

مجلد .champollion/

ينشئ Champollion مجلد .champollion/ في جذر مشروعك للحالة الداخلية. ينبغي بشكل عام إضافته إلى .gitignore — فهو تحسين محلي وليس جزءًا من مصدر المشروع:

.champollion/

الملف	الغرض	يُودَع؟
tm.json	ذاكرة الترجمة المؤقتة — تخزّن الترجمات السابقة مفهرسة بالنص المصدر + اللغة + الطريقة	لا (ذاكرة مؤقتة محلية)
xliff/*.xliff	ملفات تصدير XLIFF لمراجعة المترجمين المحترفين	لا (مؤقتة)
methods/	بيانات وصف إضافات الطرق المثبّتة	نعم (إعدادات مشتركة)
backups/	نسخ احتياطية ما قبل التغليف (ينشئها wrap --undo)	لا (شبكة أمان)

راجع ذاكرة الترجمة لمزيد من التفاصيل حول tm.json وكيف يوفّر تكاليف API.

---

واجهة برمجية للاستخدام البرمجي

لسكربتات البناء والتكاملات المخصصة، استورد مباشرة من الحزمة:

import { GeminiMethod, runSync, resolveConfig } from 'champollion';

// Use a method class directly
const gemini = new GeminiMethod();
const result = await gemini.translate(
  ['greeting', 'farewell'],
  { greeting: 'Hello', farewell: 'Goodbye' },
  { target: 'fr', name: 'French', register: 'formal', model: 'gemini-2.5-flash' },
  { cwd: process.cwd() }
);
// result = { greeting: 'Bonjour', farewell: 'Au revoir' }

عمليات التصدير المتاحة

التصدير	الوظيفة
TranslationMethod	الفئة الأساسية لجميع الطرق
LLMMethod	الفئة الأساسية لطرق LLM ‏(OpenRouter)
DirectLLMMethod	الفئة الأساسية لمزودي LLM المباشرين (OpenAI، Anthropic، Gemini)
OpenAIMethod، AnthropicMethod، GeminiMethod	فئات مزودي LLM المباشرين
DeepLMethod، MicrosoftTranslatorMethod، LibreTranslateMethod	فئات الترجمة الآلية التقليدية
GoogleTranslateMethod	Google Cloud Translation
LLMCoachedMethod	نموذج LLM موجَّه (OpenRouter + بيانات توجيه)
APIMethod	عميل API بعيد
runSync، runContentSync	خط أنابيب المزامنة الكامل
resolveConfig، resolvePairs	حل الإعدادات
validateTranslations	بوابة الجودة
loadCoachingData، findDictionaryMatches	أدوات التوجيه

إضافة مزود مخصص

وسّع DirectLLMMethod لإضافة مزود LLM جديد بنحو 40 سطرًا:

import { DirectLLMMethod } from 'champollion';

class MistralMethod extends DirectLLMMethod {
  constructor(options) {
    super(options);
    this.name = 'mistral';
  }
  _getApiKeyEnvVar()     { return 'MISTRAL_API_KEY'; }
  _getApiKeyOptionsKey() { return 'mistralApiKey'; }
  _getDefaultModel()     { return 'mistral-large-latest'; }
  _getProviderLabel()    { return 'Mistral'; }

  _buildApiRequest({ prompt, systemMessage, apiKey, model, temperature }) {
    return {
      url: 'https://api.mistral.ai/v1/chat/completions',
      headers: { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
      body: {
        model,
        messages: [
          ...(systemMessage ? [{ role: 'system', content: systemMessage }] : []),
          { role: 'user', content: prompt },
        ],
        temperature,
      },
    };
  }

  _extractResponseText(json) {
    return json.choices?.[0]?.message?.content;
  }

  // Optional but recommended: provider-specific setup help when translation fails
  getSetupHelp() {
    if (!process.env.MISTRAL_API_KEY) {
      return [
        '',
        '  ┌─ Missing API Key ─────────────────────────────────────────────┐',
        '  │ Mistral requires an API key from https://console.mistral.ai   │',
        '  │ Run: export MISTRAL_API_KEY=...                               │',
        '  └────────────────────────────────────────────────────────────────┘',
      ];
    }
    return ['        API key is set but translation failed. Check your Mistral dashboard.'];
  }
}

تحصل مجانًا على الترجمة، والتوجيه، وحلقات إعادة المحاولة، والتحقق من النماذج، ومستويات الجودة، ومساعدة الإعداد. شكل طلب HTTP وحده هو الخاص بكل مزود. بالنسبة للمحوّلات غير المعتمدة على LLM والتي تستخدم fetch() مباشرة، استخدم الأداة المساعدة المشتركة fetchWithRetry() من lib/methods/fetch-with-retry.js بدلًا من كتابة حلقة إعادة محاولة خاصة بك.

---

انظر أيضًا

• مرجع سطر الأوامر — جميع الأوامر والرايات
• طرق الترجمة — اختيار الطرق والمزج بينها
• ذاكرة الترجمة — التخزين المؤقت وتوفير التكاليف
• العمل مع المترجمين المحترفين — سير عمل XLIFF
• مواصفات الإضافات — صيغة بيانات وصف إضافات الطرق
• البنية المعمارية — كيف تترابط المكونات
• اللغات المدعومة — دعم اللغات المدمج
• كيف تعمل المزامنة — خط أنابيب الترجمة