ماذا يفحص i18n-validate؟

يجري 9 فحوصات: المفاتيح المفقودة، والمفاتيح الإضافية، والعناصر النائبة المعطوبة، وصيغ الجمع غير السليمة، واللغات المفقودة، واللغات اليتيمة، وأخطاء التحليل، والقيم الفارغة، والسلاسل غير المترجمة. يمكن تعيين كل فحص إلى خطأ أو تحذير أو إيقاف لكل لغة.

كيف أضيف التحقق من الترجمات إلى CI/CD؟

شغّل 'npx @i18n-agent/i18n-validate ./locales --format junit -o i18n-report.xml' في مسارك. تُنهي الأداة التنفيذ برمز خروج 1 عند العثور على أخطاء، ما يؤدي إلى فشل CI تلقائيًا. استخدم إخراج JUnit XML مع إجراءات مُبلِّغ الاختبارات لإضافة تعليقات مضمّنة على pull request.

ما صيغ ملفات الترجمة المدعومة؟

32 صيغة تشمل JSON وYAML وXLIFF 1.2/2.0 وAndroid XML وiOS Strings وiOS Stringsdict وXcode String Catalogs وFlutter ARB وGettext PO وJava Properties و.NET RESX وPHP/Laravel وCSV وExcel وغير ذلك. تكتشف الأداة الصيغة تلقائيًا من امتدادات الملفات.

Open Source CLI Tool

مدقّق i18n

Name: i18n Agent
Price: 0.01 EUR
Author: i18n Agent

دقّق ملفات الترجمة لرصد المفاتيح المفقودة، والعناصر النائبة المعطوبة، وتناقضات صيغ الجمع. أمر واحد. 9 فحوصات. 32 صيغة. بدون إعداد.

9 checks 32 formats Zero config Native Rust binary

المشكلة

تظل مشكلات الترجمة غير مرئية حتى يصطدم بها المستخدمون. يُظهر المفتاح المفقود مسارًا خامًا مثل "settings.billing.title" بدلًا من نص فعلي. ويعرض العنصر النائب المعطوب "{price}" كنص حرفي بدلًا من "$9.99". وقد تتسبب صيغة جمع غير سليمة في تعطل التطبيق عندما يكون العدد 0. تمر هذه الأخطاء عبر مراجعة الشيفرة لأن أحدًا لا يقارن يدويًا بين 15 ملفًا للغات المحلية.

🔑

Missing keys

Blank text or key paths shown to users

🔗

Broken placeholders

{price} displays as literal text instead of $9.99

📁

Orphaned files

Outdated translations confuse the build system

💥

Malformed files

Runtime crashes when users switch languages

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

الحل

يفحص i18n-validate جميع ملفات الترجمة لديك في مرور واحد. يكتشف تلقائيًا بنية الدليل وصيغة الملف، ويقارن كل لغة بالمرجع، ويبلغ بدقة عمّا هو خطأ وأين يقع. بدون إضافات، وبدون تكوين، وبدون شيفرة اختبار مخصصة.

Check	Severity	What it catches
missing-keys	error	Key exists in reference but is absent in a translation
extra-keys	error	Key exists in translation but not in the reference
placeholders	error	{price}, {{name}}, %s differ between languages
plural-structure	error	Plural forms are malformed or missing required categories
missing-languages	error	Expected language has no files or directory
orphaned-languages	error	Language files exist but are not in the expected list
parse-errors	error	File fails to parse (broken JSON, XML, YAML, etc.)
empty-values	warning	Key is present but the translation is an empty string
untranslated	warning	Translation is identical to the reference language

Terminal output

i18n-validate v0.1.0 — validating ./locales

  Reference: en (2 files: translation.json, apiTester.json)
  Languages: de, ja, fr, es, zh-Hans, pt-BR, ko (7 found, 7 expected)
  Layout   : directory (auto-detected)
  Formats  : i18next JSON (auto-detected)

────────────────────────────────────────────────

ERRORS (5)

  ✗ missing-keys │ translation.json
    Key "settings.billing.title"
      missing in: ja, ko

  ✗ placeholders │ translation.json
    Key "pricing.total" — expected: {price}, {currency}
      de:  found {price} only — missing {currency}

────────────────────────────────────────────────

WARNINGS (2)

  ⚠ empty-values │ translation.json
    Key "onboarding.step3.hint"
      empty in: de, fr

────────────────────────────────────────────────

  5 errors, 2 warnings across 7 languages
  ✗ Validation failed

التثبيت

ثبّته كأداة CLI عالمية باستخدام مدير الحزم المفضل لديك. تتضمن حزمة npm ملفًا ثنائيًا أصليًا مكتوبًا بـ Rust — لا حاجة إلى تجميع أو تبعيات وقت تشغيل.

Terminal

npm install -g @i18n-agent/i18n-validate

تتضمن حزمة npm ملفًا ثنائيًا أصليًا مُسبَق التجميع لأنظمة macOS وLinux وWindows. لا حاجة إلى سلسلة أدوات Rust.

الاستخدام

وجّه الأداة إلى دليل locales لديك. تكتشف تلقائيًا لغة المرجع وبنية الدليل وصيغة الملف. لا يلزم أي تكوين لمعظم المشاريع.

Terminal

# Zero-config validation
i18n-validate ./locales

# JSON output for scripting
i18n-validate ./locales --format json | jq '.summary'

# CI/CD with JUnit XML
i18n-validate ./locales --format junit -o i18n-report.xml

التكامل مع CI/CD

أضِف التحقق من الترجمات إلى مسار pull request لديك. تُخرج الأداة JUnit XML الذي يتكامل مع مُبلِّغات اختبارات GitHub Actions، وArtifacts في GitLab CI، وأي نظام CI يدعم JUnit.

.github/workflows/validate-i18n.yml

name: Validate Translations
on:
  pull_request:
    paths: ['locales/**', 'public/locales/**']

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

      - name: Validate translations
        run: npx @i18n-agent/i18n-validate ./locales --format junit -o i18n-report.xml

      - uses: dorny/test-reporter@v1
        if: always()
        with:
          name: i18n validation
          path: i18n-report.xml
          reporter: java-junit

The tool exits with code 1 when errors are found, so it naturally fails CI. Use --strict to also fail on warnings.

الصيغ المدعومة

بدعم من i18n-convert، يدعم المُدقِّق 32 صيغة لملفات i18n جاهزة للاستخدام. لا حاجة لإضافات أو تكوين خاص بكل صيغة — تكتشف الأداة الصيغة تلقائيًا من امتدادات الملفات والمحتوى.

Mobile & Desktop

Android XML, Xcode String Catalog, iOS Strings, iOS Stringsdict, Flutter ARB, Qt Linguist

Web & Frameworks

Structured JSON, i18next JSON, JSON5, HJSON, YAML (Rails), YAML (Plain), JavaScript, TypeScript, PHP/Laravel, NEON

Standards & Exchange

XLIFF 1.2, XLIFF 2.0, Gettext PO, TMX, .NET RESX, Java Properties

Data & Other

CSV, Excel (.xlsx), TOML, INI, SRT Subtitles, Markdown, Plain Text

التكوين

بالنسبة لمعظم المشاريع، يعمل بدون أي إعداد. عندما تحتاج إلى تحكّم — مثل تجاوز شدة الفحوصات، أو تحديد اللغات المتوقعة، أو استبعاد لغات قيد العمل — أنشئ ملف .i18n-validate.toml في جذر مشروعك.

.i18n-validate.toml

# .i18n-validate.toml
ref = "en"
expect = ["de", "ja", "fr", "es", "zh-Hans", "pt-BR", "ko"]

[checks]
missing-keys = "error"
extra-keys = "error"
placeholders = "error"
empty-values = "warning"
untranslated = "warning"

[languages.ko]
missing-keys = "warning"    # Korean is WIP

[languages.ar]
skip = true                 # Exclude from validation