Какво проверява i18n-validate?

Инструментът извършва 9 проверки: липсващи ключове, излишни ключове, повредени заместители, неправилно форматирани форми за множествено число, липсващи езици, езикови версии без съответствие, грешки при синтактичния анализ, празни стойности и непреведени текстове. За всеки език всяка проверка може да бъде зададена като грешка, предупреждение или изключена.

Как да добавя проверка на преводите към CI/CD?

Изпълнете 'npx @i18n-agent/i18n-validate ./locales --format junit -o i18n-report.xml' във Вашия пайплайн. Когато бъдат открити грешки, инструментът завършва с код 1 и CI автоматично отчита неуспех. Използвайте изходния файл във формат JUnit XML с инструменти за отчитане на тестове, за да добавяте бележки директно в PR.

Кои файлови формати за превод се поддържат?

Поддържат се 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 Validator

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". Неправилно форматирана форма за множествено число предизвиква срив, когато броят е нула. Тези грешки остават незабелязани при проверката на кода, защото никой не сравнява ръчно 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.

Употреба

Задайте на инструмента директорията с Вашите езикови версии. Той автоматично разпознава референтния език, подредбата на директориите и файловия формат. За повечето проекти не е необходима конфигурация.

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

Добавете проверка на преводите към процеса за заявки за сливане. Инструментът създава JUnit XML, който се интегрира с инструментите за отчитане на тестове в GitHub Actions, артефактите на 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

Конфигурация

За повечето проекти не е необходима конфигурация. Когато Ви е необходим повече контрол — за да промените сериозността на проверките, да зададете очакваните езици или да изключите езиците в процес на работа (WIP) — създайте файл .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