
التحقق من الترجمات في CI: أتمتة فحوص i18n في خطك
أخطاء الترجمة غير مرئية في مراجعة الكود. مفتاح مفقود، أو عنصر نائب معطوب، أو صيغة جمع غير سليمة؛ لا يظهر أيٌّ من ذلك في diff. يلتقط التحقق على مستوى CI هذه المشكلات قبل وصولها إلى الإنتاج.
لماذا تفلت أخطاء الترجمة من مراجعة الكود؟
يضيف مطوّر 10 مفاتيح جديدة إلى en.json ويحدّث كود الميزة. يراجع مُراجع PR الكود، ويتحقق من السلاسل الإنجليزية، ثم يوافق. لا أحد يقارن ملفات اللغات الأربعة عشر الأخرى. تصل ثلاثة أخطاء إلى الإنتاج: de.json تفتقد مفتاحين (يرى المستخدمون الألمان مسارات مفاتيح خام)، وfr.json تحتوي على عنصر نائب {count} معطوب (يرى المستخدمون الفرنسيون {count} حرفيًا)، وja.json تحتوي على جمع ICU غير سليم (يرى المستخدمون اليابانيون تعطّلًا). يمكن منع ذلك بفحص CI مدته 30 ثانية.
ثبّت i18n-validate
أضف i18n-validate إلى مشروعك بوصفه اعتمادًا للتطوير. يدعم صيغ JSON وYAML وPO وXLIFF وARB مباشرةً؛ ولا يلزم أي إعداد للاستخدام الأساسي.
npm install --save-dev @anthropic/i18n-validateتكامل GitHub Actions
أضف i18n-validate كخطوة في سير عمل pull request. تُنهي الأداة التنفيذ برمز خروج 1 عند العثور على أخطاء، ما يؤدي إلى فشل فحص PR. استخدم إخراج JUnit XML مع إجراء مُبلّغ الاختبارات للحصول على تعليقات توضيحية داخلية مباشرة على diff الخاص بـ PR.
# .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تكامل GitLab CI
أضف مهمة تحقق من الترجمات إلى خط .gitlab-ci.yml. يدعم GitLab آثار JUnit XML أصلًا؛ ارفع تقرير التحقق لتظهر الأخطاء في تبويب Test لطلب الدمج.
# .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/**/*خطاف ما قبل الالتزام (Pre-Commit Hook)
للحصول على ملاحظات أسرع، شغّل التحقق كخطاف pre-commit. يلتقط ذلك المشكلات قبل أن تصل إلى CI، ما يوفر وقت خط الأنابيب ويقلل دورات التغذية الراجعة. استخدم Husky (JS) أو pre-commit (Python) لإدارة الخطافات.
# .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الإعداد ومستويات الشدة
خصص سلوك التحقق باستخدام ملف إعداد .i18n-validate.toml. عيّن شدة الفحص (error, warning, off) لكل قاعدة، وحدد اللغات المتوقعة، واستبعد لغات WIP، واضبط تنسيق الإخراج. في CI، لا يفشل خط الأنابيب إلا بسبب errors؛ أما warnings فتظهر في التقرير لكنها لا تمنع التنفيذ.
// 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
أو انقر للاستعراض
اللغات المستهدفة