Skip to main content
Open Source CLI Tool

i18n Validator

檢查翻譯檔案中的缺失鍵、損壞的預留位置和複數不一致。一條命令,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),而且每個項目都要編寫自訂測試程式碼。翻譯缺陷往往到執行階段才被發現,此時用戶已經看到損壞的 UI。

解決方案

i18n-validate 一次掃描所有翻譯檔案。它會自動檢測目錄佈局和檔案格式,將每種語言與參考語言進行比較,並準確報告問題內容和位置。無需外掛程式、設定或自訂測試程式碼。

CheckSeverityWhat it catches
missing-keyserrorKey exists in reference but is absent in a translation
extra-keyserrorKey exists in translation but not in the reference
placeholderserror{price}, {{name}}, %s differ between languages
plural-structureerrorPlural forms are malformed or missing required categories
missing-languageserrorExpected language has no files or directory
orphaned-languageserrorLanguage files exist but are not in the expected list
parse-errorserrorFile fails to parse (broken JSON, XML, YAML, etc.)
empty-valueswarningKey is present but the translation is an empty string
untranslatedwarningTranslation 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 產物以及任何支援 JUnit 的 CI 系統整合。

.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

立即試用 i18n Agent

將翻譯檔案拖放到此處

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

或點擊選擇檔案

目標語言

無需註冊即時估價

常見問題