Skip to main content

التحقق من الترجمات في CI: أتمتة فحوص i18n في خطك

أخطاء الترجمة غير مرئية في مراجعة الكود. مفتاح مفقود، أو عنصر نائب معطوب، أو صيغة جمع غير سليمة؛ لا يظهر أيٌّ من ذلك في diff. يلتقط التحقق على مستوى CI هذه المشكلات قبل وصولها إلى الإنتاج.

1

لماذا تفلت أخطاء الترجمة من مراجعة الكود؟

يضيف مطوّر 10 مفاتيح جديدة إلى en.json ويحدّث كود الميزة. يراجع مُراجع PR الكود، ويتحقق من السلاسل الإنجليزية، ثم يوافق. لا أحد يقارن ملفات اللغات الأربعة عشر الأخرى. تصل ثلاثة أخطاء إلى الإنتاج: de.json تفتقد مفتاحين (يرى المستخدمون الألمان مسارات مفاتيح خام)، وfr.json تحتوي على عنصر نائب {count} معطوب (يرى المستخدمون الفرنسيون {count} حرفيًا)، وja.json تحتوي على جمع ICU غير سليم (يرى المستخدمون اليابانيون تعطّلًا). يمكن منع ذلك بفحص CI مدته 30 ثانية.

لأخطاء الترجمة خاصية فريدة: هي غير مرئية للمطور، وغير مرئية للمراجع، ولا تصبح مرئية إلا للمستخدمين ضمن لغة محددة. التحقق في CI هو الطريقة الموثوقة الوحيدة لالتقاطها قبل الإنتاج.
2

ثبّت i18n-validate

أضف i18n-validate إلى مشروعك بوصفه اعتمادًا للتطوير. يدعم صيغ JSON وYAML وPO وXLIFF وARB مباشرةً؛ ولا يلزم أي إعداد للاستخدام الأساسي.

Terminal
npm install --save-dev @anthropic/i18n-validate
3

تكامل GitHub Actions

أضف i18n-validate كخطوة في سير عمل pull request. تُنهي الأداة التنفيذ برمز خروج 1 عند العثور على أخطاء، ما يؤدي إلى فشل فحص PR. استخدم إخراج JUnit XML مع إجراء مُبلّغ الاختبارات للحصول على تعليقات توضيحية داخلية مباشرة على diff الخاص بـ PR.

.github/workflows/i18n-validate.yml
# .github/workflows/i18n-validate.yml
name: Validate Translations

on:
  pull_request:
    paths:
      - 'src/locales/**'
      - 'public/locales/**'

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

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

      - name: Install dependencies
        run: npm ci

      - name: Validate translation files
        run: npx i18n-validate \
          --source src/locales/en.json \
          --targets 'src/locales/*.json' \
          --check-missing \
          --check-unused \
          --check-placeholders \
          --check-plurals \
          --min-coverage 95 \
          --junit-output reports/i18n.xml

      - name: Upload report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: i18n-validation-report
          path: reports/i18n.xml
ثبّت إصدار i18n-validate في سير العمل لتجنب أعطال غير متوقعة ناتجة عن قواعد تحقق جديدة. استخدم @latest في بيئات التطوير فقط.
4

تكامل GitLab CI

أضف مهمة تحقق من الترجمات إلى خط .gitlab-ci.yml. يدعم GitLab آثار JUnit XML أصلًا؛ ارفع تقرير التحقق لتظهر الأخطاء في تبويب Test لطلب الدمج.

.gitlab-ci.yml
# .gitlab-ci.yml
i18n-validate:
  stage: test
  image: node:20
  script:
    - npm ci
    - npx i18n-validate \
        --source src/locales/en.json \
        --targets 'src/locales/*.json' \
        --check-missing \
        --check-unused \
        --check-placeholders \
        --min-coverage 95 \
        --junit-output reports/i18n.xml
  artifacts:
    reports:
      junit: reports/i18n.xml
  only:
    changes:
      - src/locales/**/*
5

خطاف ما قبل الالتزام (Pre-Commit Hook)

للحصول على ملاحظات أسرع، شغّل التحقق كخطاف pre-commit. يلتقط ذلك المشكلات قبل أن تصل إلى CI، ما يوفر وقت خط الأنابيب ويقلل دورات التغذية الراجعة. استخدم Husky (JS) أو pre-commit (Python) لإدارة الخطافات.

.husky/pre-commit
# .husky/pre-commit
#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

# Only validate if translation files changed
CHANGED_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -E '(locales|i18n|translations)/')

if [ -n "$CHANGED_FILES" ]; then
  echo "Translation files changed, validating..."
  npx i18n-validate \
    --source src/locales/en.json \
    --targets 'src/locales/*.json' \
    --check-missing \
    --check-placeholders
fi
تعمل خطافات pre-commit مع كل التزام، لذا احرص على أن تكون سريعة. استخدم العلم --locales للتحقق من اللغات التي تغيّرت في الالتزام الحالي فقط بدلًا من جميع اللغات. يحافظ ذلك على زمن تنفيذ الخطاف تحت 2 ثانية في معظم المشاريع.
6

الإعداد ومستويات الشدة

خصص سلوك التحقق باستخدام ملف إعداد .i18n-validate.toml. عيّن شدة الفحص (error, warning, off) لكل قاعدة، وحدد اللغات المتوقعة، واستبعد لغات WIP، واضبط تنسيق الإخراج. في CI، لا يفشل خط الأنابيب إلا بسبب errors؛ أما warnings فتظهر في التقرير لكنها لا تمنع التنفيذ.

i18n-validate.config.json
// i18n-validate.config.json
{
  "source": "src/locales/en.json",
  "targets": "src/locales/*.json",
  "checks": {
    "missing": true,         // Keys in source missing from target
    "unused": true,          // Keys in target not in source
    "placeholders": true,    // Mismatched {variables}
    "plurals": true,         // Missing CLDR plural forms
    "icu": true,             // ICU syntax validation
    "emptyValues": true,     // Empty string values
    "duplicateValues": false // Same value as source (untranslated)
  },
  "minCoverage": 95,
  "exclude": [
    "src/locales/pseudo.json"
  ],
  "junitOutput": "reports/i18n.xml",
  "format": "json"          // json | yaml | po | xliff
}

جرّب i18n Agent الآن

أفلت ملف الترجمة هنا

JSON, YAML, PO, XML, CSV, Markdown, Properties

أو انقر للاستعراض

اللغات المستهدفة

لا حاجة إلى التسجيلتقدير فوري

الأسئلة الشائعة حول التحقق من الترجمات في CI