Skip to main content
Open Source CLI Tool

i18n Validator

Lint translation files for missing keys, broken placeholders, and plural inconsistencies. One command. 9 checks. 32 formats. Zero config.

9 checks 32 formats Zero config Native Rust binary

The Problem

Translation issues are invisible until users hit them. A missing key shows a raw path like "settings.billing.title" instead of real text. A broken placeholder renders "{price}" as literal text instead of "$9.99". A malformed plural crashes when the count is zero. These bugs slip through code review because nobody diffs 15 locale files manually.

🔑

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

Most validation tools are format-specific (JSON-only, YAML-only) and require custom test code for each project. Translation bugs are often caught only at runtime when users see broken UI.

The Solution

i18n-validate scans all your translation files in one pass. It auto-detects your directory layout and file format, compares every language against the reference, and reports exactly what is wrong and where. No plugins, no configuration, no custom test code.

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

Installation

Install as a global CLI tool using your preferred package manager. The npm package bundles a native Rust binary — no compilation or runtime dependencies required.

Terminal
npm install -g @i18n-agent/i18n-validate
The npm package bundles a pre-compiled native binary for macOS, Linux, and Windows. No Rust toolchain needed.

Usage

Point the tool at your locales directory. It auto-detects the reference language, directory layout, and file format. Zero configuration required for most projects.

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 Integration

Add translation validation to your pull request pipeline. The tool outputs JUnit XML that integrates with GitHub Actions test reporters, GitLab CI artifacts, and any CI system that supports 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.

Supported Formats

Powered by i18n-convert, the validator supports 32 i18n file formats out of the box. No format-specific plugins or configuration needed — the tool auto-detects the format from file extensions and content.

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

Configuration

For most projects, zero config works. When you need control — override check severity, set expected languages, or exclude WIP languages — create a .i18n-validate.toml file in your project root.

.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

Related Guides

Try i18n Agent Now

Drop your translation file here

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

or click to browse

Target languages

No signup requiredInstant estimate

Frequently Asked Questions