أوضاع البناء

يدعم @lingo.dev/compiler وضعين للبناء يتحكمان في متى وكيف يتم إنشاء الترجمات.

نظرة عامة على الأوضاع

وضع الترجمة

الغرض: إنشاء الترجمات عند الطلب أثناء البناء.

{
  buildMode: "translate"
}

السلوك:

• يفحص الكود بحثاً عن النصوص القابلة للترجمة
• يتحقق من .lingo/metadata.json للترجمات الموجودة
• ينشئ الترجمات المفقودة عبر موفر LLM المُكوّن
• يحدّث .lingo/metadata.json بالترجمات الجديدة
• يفشل البناء إذا فشل إنشاء الترجمة

متى يُستخدم:

• التطوير المحلي (مع usePseudotranslator: true)
• خطوط CI/CD (مع موفري LLM الحقيقيين)
• الإعداد الأولي وإنشاء الترجمات

يتطلب:

• مفتاح API صالح للموفر المُكوّن (أو تفعيل المترجم الزائف)
• اتصال شبكة بموفر LLM

وضع الذاكرة المؤقتة فقط

الغرض: البناء باستخدام الترجمات المُنشأة مسبقاً فقط.

{
  buildMode: "cache-only"
}

السلوك:

• يقرأ الترجمات من .lingo/metadata.json
• لا يتم إجراء استدعاءات API
• يفشل البناء إذا كانت الترجمات مفقودة لأي لغة
• بناءات سريعة وحتمية

متى يُستخدم:

• بناءات الإنتاج
• عمليات النشر بدون مفاتيح API
• البيئات ذات الوصول المحدود للشبكة

يتطلب:

• .lingo/metadata.json مع ترجمات لجميع اللغات
• ترجمات مُنشأة مسبقاً في CI أو التطوير

سير العمل الموصى به

1. التطوير المحلي

استخدم المترجم الزائف للحصول على ملاحظات فورية:

{
  buildMode: "translate",
  dev: {
    usePseudotranslator: true,
  }
}

الفوائد:

• ترجمات وهمية فورية
• بدون تكاليف API
• رؤية ما يتم ترجمته بالضبط
• اختبار واجهة المستخدم بأطوال نصوص متفاوتة

2. خط أنابيب CI/CD

إنشاء ترجمات حقيقية في CI:

{
  buildMode: "translate",
  dev: {
    usePseudotranslator: false,
  }
}

الإعداد في CI:

# GitHub Actions example
- name: Install dependencies
  run: pnpm install

- name: Generate translations
  env:
    LINGODOTDEV_API_KEY: ${{ secrets.LINGODOTDEV_API_KEY }}
  run: pnpm run build

- name: Commit translations
  run: |
    git config user.name "github-actions[bot]"
    git config user.email "github-actions[bot]@users.noreply.github.com"
    git add .lingo/
    git commit -m "chore: update translations" || exit 0
    git push

الفوائد:

• يتم إنشاء الترجمات الحقيقية مرة واحدة لكل نشر
• يتم الالتزام بها في نظام التحكم في الإصدارات
• لا تحتاج إصدارات الإنتاج إلى مفاتيح API

3. إصدار الإنتاج

استخدام الترجمات المخزنة مؤقتاً فقط:

{
  buildMode: "cache-only",
}

الفوائد:

• لا حاجة لمفاتيح API
• إصدارات سريعة
• حتمية—نفس المدخلات تنتج دائماً نفس المخرجات
• لا توجد تبعيات شبكة خارجية

تجاوز متغير البيئة

تجاوز وضع الإصدار عبر متغير البيئة:

# Force cache-only mode
LINGO_BUILD_MODE=cache-only npm run build

# Force translate mode
LINGO_BUILD_MODE=translate npm run build

هذا مفيد لبيئات النشر حيث تريد فرض وضع التخزين المؤقت فقط دون تعديل الإعدادات.

التعامل مع الترجمات المفقودة

في وضع الترجمة

إذا فشلت الترجمة:

Error: Failed to generate translation for locale "es":
  - Hash: abc123def
  - Source text: "Welcome to our app"
  - Provider: lingo.dev
  - Reason: API key invalid

الحل: إصلاح مفتاح API، إعادة تشغيل الإصدار.

في وضع التخزين المؤقت فقط

إذا كانت الترجمات مفقودة:

Error: Missing translations for locale "es":
  - Hash: abc123def
  - Source text: "Welcome to our app"
  - File: app/page.tsx:12

Run with buildMode: "translate" to generate missing translations.

الحل: تشغيل إصدار بوضع translate لإنشاء الترجمات المفقودة، ثم الالتزام بـ .lingo/.

الترجمة التدريجية

يستخدم المترجم تجزئة المحتوى لتحديد ما يحتاج إلى ترجمة:

1. تحصل كل سلسلة نصية قابلة للترجمة على hash مستقر
2. يعتمد الـ hash على النص المصدر + السياق
3. إذا كان الـ hash موجودًا في .lingo/metadata.json، يتم إعادة استخدام الترجمة
4. النص الجديد أو المعدل فقط هو الذي يؤدي إلى إعادة الترجمة

النتيجة: تدفع مقابل الترجمات مرة واحدة فقط. عمليات البناء اللاحقة تعيد استخدام الترجمات المخزنة مؤقتًا.

أمثلة على إعدادات CI

GitHub Actions

name: Generate Translations

on:
  push:
    branches: [main]
  pull_request:

jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: pnpm/action-setup@v2
        with:
          version: 8

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: "pnpm"

      - name: Install dependencies
        run: pnpm install

      - name: Generate translations
        env:
          LINGODOTDEV_API_KEY: ${{ secrets.LINGODOTDEV_API_KEY }}
        run: pnpm run build

      - name: Commit translations
        if: github.event_name == 'push'
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git add .lingo/
          git diff --quiet && git diff --staged --quiet || git commit -m "chore: update translations"
          git push

GitLab CI

stages:
  - translate

generate-translations:
  stage: translate
  script:
    - pnpm install
    - pnpm run build
    - git config user.name "GitLab CI"
    - git config user.email "[email protected]"
    - git add .lingo/
    - git diff --quiet && git diff --staged --quiet || git commit -m "chore: update translations"
    - git push origin HEAD:$CI_COMMIT_REF_NAME
  only:
    - main

الأسئلة الشائعة

هل أحتاج إلى مفاتيح API في بيئة الإنتاج؟ لا. استخدم buildMode: "cache-only" في بيئة الإنتاج. يتم إنشاء الترجمات مسبقًا في CI.

ماذا لو نسيت إنشاء الترجمات في CI؟ سيفشل بناء الإنتاج مع رسالة خطأ واضحة تسرد الترجمات المفقودة. قم بإنشائها في CI، ثم commit، وأعد النشر.

هل يمكنني استخدام وضع الترجمة في بيئة الإنتاج؟ نعم، لكن غير موصى به. يجعل عمليات البناء غير حتمية ويتطلب مفاتيح API في بيئة الإنتاج. من الأفضل إنشاء الترجمات في CI.

كيف أختبر وضع cache-only محليًا؟

1. قم بإنشاء الترجمات باستخدام وضع translate
2. انتقل إلى وضع cache-only
3. قم بتشغيل البناء—يجب أن ينجح باستخدام الترجمات المخزنة مؤقتًا

ماذا لو تغير النص المصدر؟ يتغير الـ hash، لذا يتم إنشاء ترجمة جديدة (في وضع translate). يتم الاحتفاظ بالترجمة القديمة في .lingo/metadata.json للسجل.

هل أقوم بعمل commit لـ .lingo/ إلى git؟ نعم. يجب أن يكون دليل .lingo/ تحت إدارة الإصدارات. يحتوي على ذاكرة التخزين المؤقت للترجمة الخاصة بك.

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

• موفرو الترجمة — إعداد موفري LLM لوضع الترجمة
• أدوات التطوير — استخدام المترجم الزائف بفعالية
• أفضل الممارسات — سير عمل CI/CD الموصى به