Scribe

الترجمة

كيفية عمل الترجمة في Scribe: تتبع التحديثات، نموذج Gemini، التحقق من المخرجات، تقارير التكلفة، وأدوات المراجعة.

View as Markdown

يُترجم Scribe المصدر الإنجليزي إلى كل اللغات الأخرى باستخدام نموذج لغوي كبير (Gemini)، ويخزن النتائج في SQLite. لا حاجة لتعديل ملفات اللغات يدوياً، فكل ما عليك هو تعديل النص الإنجليزي وتشغيل scribe translate ثم حفظ التغييرات.

ما الذي يتم ترجمته

يُرسل عنصران فقط لكل مستند إلى المترجم:

  1. حقول الواجهة الأمامية (Frontmatter) المحددة بـ field.translatable()، بما في ذلك الحقول المتداخلة داخل المصفوفات والكائنات.
  2. محتوى MDX الأساسي.

تُنسخ باقي العناصر (field.structural() والعلاقات والحقول المدمجة) من المستند الإنجليزي عند التحميل. وفي حال استخدام slugStrategy: "localized"، يُنتج المترجم أيضاً رابطاً مخصصاً لكل لغة (بتنسيق kebab-case بترميز ASCII، مع كتابة الحروف بأقرب مقابل لها للغات غير اللاتينية).

عدم ترجمتك للغة معينة لا يسبب مشكلة عند التشغيل: حيث تقدم دالة resolve() أقرب ترجمة متاحة عبر سلسلة اللغات البديلة. على سبيل المثال: تعود لغة pt-BR إلى pt، ثم إلى اللغة الافتراضية، مما يتيح لك إضافة اللغات تدريجياً.

تتبع التحديثات

تحفظ كل ترجمة بصمة تشفير SHA-256 للمحتوى الإنجليزي القابل للترجمة الذي استندت إليه. ولا يعيد scribe translate ترجمة الصفحة إلا في الحالات التالية:

  • عدم وجود ترجمة سابقة لهذه اللغة (مفقودة).
  • أو تغير المحتوى الإنجليزي القابل للترجمة منذ آخر ترجمة (قديمة).

لا يؤدي تعديل الحقول الهيكلية أو مدخلات _redirects.json إلى اعتبار الترجمات قديمة، لأن هذه الحقول لا تُترجم أساساً.

التحقق من المخرجات

لا تُحفظ الترجمة إلا إذا اجتازت فحصين أساسيين:

  1. يجب أن يكون نص MDX الناتج قابلاً للتحليل (بعد معالجة أخطاء الهروب وعلامات الاقتباس في سمات JSX التي قد يخطئ فيها النموذج أحياناً).
  2. يجب أن تتطابق حقول الواجهة الأمامية الناتجة مجدداً مع مخطط Zod الكامل الخاص بك.

تُعاد محاولة ترجمة العناصر التي تفشل في التحقق مرة واحدة تلقائياً في نهاية العملية، مع تزويد النموذج بأخطاء التحقق ليتمكن من تصحيحها (تُعاد المحاولة في عمليات الدفعات كمهمة إضافية واحدة بنفس معدل الدفعات). وتُدرج أي عناصر تفشل مجدداً في الملخص النهائي مع خطأها الجديد، وتتوقف العملية بخطأ. وبهذا نضمن ألا يصل أي مخرج سيئ من النموذج إلى قاعدة البيانات، وبالتالي لا يظهر إطلاقاً في بيئة الإنتاج.

التشغيل

export GEMINI_API_KEY=...        # يُقرأ أيضاً من ملفات .env / .env.local

scribe status                     # التغطية لكل نوع ولغة
scribe translate                  # واجهة اختيار تفاعلية في الطرفية
scribe translate --locale fr de   # تحديد لغات معينة
scribe translate --preset active  # مجموعة localePresets من الإعدادات
scribe translate --type blog      # نوع محتوى واحد (مفصول بفواصل: --type blog,glossary)
scribe translate --slug my-post   # مستند واحد
scribe translate --dry-run        # عرض قائمة العمل وتقدير التكلفة دون حفظ أي شيء
scribe translate --force          # إعادة الترجمة حتى لو تطابقت البصمات
scribe translate --strategy missing-only   # تخطي المحتوى القديم وملء الفراغات فقط
scribe translate --batch          # فرض وضع الدفعات (الافتراضي)
scribe translate --direct         # استدعاءات API لكل صفحة مع نتائج فورية
scribe translate --resume         # استئناف مهام الدفعات المعلقة دون إرسال مهام جديدة
scribe translate --concurrency 5  # طلبات متوازية (في الوضع المباشر فقط)
scribe translate --model gemini-3.1-pro

عند التشغيل في الطرفية، يعرض scribe translate واجهة تقدم مباشرة توضح حالة مهام الدفعات، ونتائج كل عنصر، وعدد الرموز المستخدمة، والتكلفة التقديرية بالدولار. تُحتسب رموز التفكير (Thinking tokens) ضمن الاستهلاك المعروض لتتطابق التقديرات مع فواتير Google. يمكنك استخدام إضافة --no-progress (أو التشغيل غير التفاعلي في بيئات CI) للحصول على سجلات نصية بسيطة سطراً بسطر.

يقوم أمر --dry-run بطباعة قائمة العمل دون حفظ أي بيانات، مع عرض تقدير لعدد الرموز والتكلفة بالدولار لكل عنصر وفي الإجمالي، محسوبة بناءً على الطلب الفعلي وحجم النص الإنجليزي. وفي وضع --batch، يطبق التقدير خصم الدفعات ليعكس التكلفة الحقيقية بدقة.

بعد ذلك، قم بحفظ التغييرات في .scribe/store.sqlite.

وضع الدفعات والاستئناف

افتراضياً، تُرسل قائمة العمل بالكامل عبر Gemini Batch API، والذي يعمل بنصف تكلفة الرموز مقارنة بالاستدعاءات المباشرة. يخطط Scribe لكل طلب مسبقاً (مهمة واحدة لكل نموذج، وتُقسّم للقوائم الكبيرة جداً)، ويُرسل جميع المهام دفعة واحدة، ثم يتابعها معاً ويحفظ نتائج كل مهمة فور اكتمالها. تكتمل مهام الدفعات عادةً خلال دقائق، لكن Google تضمن اكتمالها خلال 24 ساعة كحد أقصى، لذا ينتظر الأمر بدلاً من جلب النتائج صفحة بصفحة.

تُسجل كل مهمة في قاعدة بيانات SQLite قبل بدء المتابعة، مع نسخة من المصدر الإنجليزي الذي أُرسل منه كل عنصر. هذا يجعل مقاطعة العمليات آمنة تماماً:

  • يمكنك الإلغاء أثناء المتابعة (Ctrl+C) ولن تفقد شيئاً.
  • يتحقق scribe translate --resume من المهام المعلقة، ويستوعب المكتملة منها، ولا يُرسل أي جديد.
  • تشغيل scribe translate بشكل طبيعي يستأنف أيضاً المهام المعلقة أولاً، ولا تُرسل العناصر قيد المعالجة مرتين أبداً.
  • يمكنك تعديل صفحة إنجليزية أثناء معالجة دفعتها بأمان: تُحفظ النتيجة بناءً على النسخة التي تُرجمت منها، ثم تُعتبر قديمة في التشغيل التالي.

هل تفضل الحصول على نتائج فورية صفحة بصفحة بالسعر الكامل؟ استخدم --direct الذي يعيد استدعاءات API الفردية مع التوازي عبر --concurrency. في الطرفية، تتيح لك واجهة الاختيار التفاعلية نفس الخيار. تُعاد محاولة أخطاء API المؤقتة (429، 5xx، انقطاع الشبكة) تلقائياً بزيادة أسية في كلا الوضعين.

توجيه المترجم

التعليمات المدمجة مُصممة للترجمة الإبداعية وليس الترجمة الحرفية. يكتب النموذج بأسلوب كاتب محتوى محلي لإنتاج نسخة ملائمة للسوق: فهو يعيد صياغة التعابير والتلاعب اللفظي بدلاً من ترجمتها كلمة بكلمة، ويطبق القواعد المطبعية المحلية (علامات الاقتباس والمسافات حول علامات الترقيم). تُضاف إعدادات context وrules وprompt الخاصة بك فوق هذا الإطار الأساسي.

الإعدادات الافتراضية للمشروع والتجاوزات لكل نوع محتوى:

export default defineConfig({
  translate: {
    context: "MyBrand هو منتج B2B SaaS. لا تقم أبداً بترجمة اسم العلامة التجارية MyBrand.",
    rules: ["حافظ على دقة الأرقام والإحصائيات."],
  },
  types: [
    defineContentType({
      id: "blog",
      // ...
      translate: {
        rules: [
          "حافظ على جميع وسوم وعناصر وروابط MDX/JSX كما هي تماماً.",
          "قم بترجمة نص الرابط؛ لا تغير أبداً مسارات href.",
        ],
      },
    }),
  ],
});
الخيارالنطاقالوصف
contextالمشروع + النوعسياق العلامة التجارية/المجال الذي يُضاف قبل كل طلب (تُدمج سياقات المشروع والنوع معاً).
rulesالمشروع + النوعقواعد إضافية تُلحق بالقواعد الافتراضية.
promptالمشروع أو النوعتعليمات تعريب إضافية تُضاف قبل توجيه اللغة المستهدفة (يُضاف اسم اللغة ورمزها دائماً).
defaultModel / modelالمشروع / النوعمُعرّف نموذج Gemini. الافتراضي: gemini-3.1-pro (يمكن تغييره أيضاً عبر متغير البيئة PROSE_GEMINI_MODEL أو عبر --model).

تشمل القواعد المدمجة (التي تُطبق دائماً) ما يلي: عدم ترجمة أسماء العلامات التجارية إلا إذا كان لها اسم محلي معروف، وإرجاع نصوص MDX بفواصل أسطر حقيقية (وليس \n المتجاوزة)، وتصحيح علامات الاقتباس لسمات JSX عندما تحتوي القيم على علامات اقتباس مزدوجة.

مراجعة الترجمات

scribe history blog my-post fr    # الجدول الزمني للنسخ الإنجليزية لصفحة واحدة
scribe studio                     # واجهة ويب للقراءة فقط على المنفذ :3600

ترتبط كل ترجمة بنسخة من المصدر الإنجليزي الذي استندت إليه (محفوظة في نفس ملف SQLite)، مما يتيح لك تدقيق متى ومما وبأي نموذج تمت ترجمة الصفحة. يطبع scribe history هذا الجدول الزمني؛ بينما يعرض الاستوديو التغطية لكل لغة، وقائمة العمل الحالية للمفقود/القديم، والتفاصيل لكل مستند مع عرض النسخة الأصلية بجوار الترجمة المحفوظة.

مجموعات اللغات المسبقة

لإصدار اللغات تدريجياً، يمكنك تسمية مجموعات اللغات في الإعدادات واستهدافها باستخدام --preset:

localePresets: {
  active: ["fr", "es", "ja"],
  ultraLight: ["fr"],
}
scribe translate --preset ultraLight
الترجمة · Scribe