¿Qué comprueba i18n-validate?

Ejecuta 9 comprobaciones: claves ausentes, claves adicionales, marcadores rotos, formas plurales mal construidas, idiomas ausentes, idiomas huérfanos, errores de análisis, valores vacíos y cadenas sin traducir. Cada comprobación puede configurarse por idioma como error, advertencia o desactivada.

¿Cómo añado la validación de traducciones a CI/CD?

Ejecute 'npx @i18n-agent/i18n-validate ./locales --format junit -o i18n-report.xml' en su proceso. La herramienta termina con el código 1 cuando encuentra errores, por lo que CI falla de forma natural. Utilice la salida XML JUnit con acciones de informes de pruebas para incluir anotaciones en línea en la solicitud de incorporación.

¿Qué formatos de archivo de traducción se admiten?

32 formatos, como JSON, YAML, XLIFF 1.2/2.0, XML de Android, Strings y Stringsdict de iOS, catálogos de cadenas de Xcode, ARB de Flutter, PO de Gettext, Java Properties, .NET RESX, PHP/Laravel, CSV y Excel, entre otros. La herramienta detecta automáticamente el formato por la extensión.

Open Source CLI Tool

Validador de i18n

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

Analice archivos de traducción para detectar claves ausentes, marcadores rotos e incoherencias de plural. Un comando. 9 comprobaciones. 32 formatos. Sin configuración.

9 checks 32 formats Zero config Native Rust binary

El problema

Los problemas de traducción son invisibles hasta que afectan a los usuarios. Una clave ausente muestra una ruta sin procesar como «settings.billing.title» en vez de texto real. Un marcador roto renderiza «{price}» como texto literal en vez de «9,99 €». Un plural mal formado provoca un bloqueo cuando el número es cero. Estos errores escapan a la revisión porque nadie compara manualmente 15 archivos regionales.

🔑

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

La mayoría de los validadores están ligados a un formato —solo JSON o solo YAML— y exigen código de prueba personalizado para cada proyecto. A menudo, los errores de traducción solo se detectan durante la ejecución, cuando los usuarios ven una interfaz rota.

La solución

i18n-validate analiza todos sus archivos de traducción en una sola pasada. Detecta automáticamente la disposición de directorios y el formato, compara cada idioma con la referencia e indica exactamente qué está mal y dónde. Sin plugins, configuración ni código de prueba personalizado.

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

Instalación

Instálelo como herramienta de CLI global mediante el gestor de paquetes que prefiera. El paquete npm incluye un binario nativo de Rust, sin necesidad de compilar ni instalar dependencias de ejecución.

Terminal

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

El paquete npm incluye un binario nativo precompilado para macOS, Linux y Windows. No necesita las herramientas de Rust.

Uso

Indique a la herramienta el directorio de configuraciones regionales. Detectará automáticamente el idioma de referencia, la disposición de directorios y el formato. La mayoría de los proyectos no requiere configuración.

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

Integración con CI/CD

Añada la validación de traducciones al proceso de solicitudes de incorporación. La herramienta genera XML JUnit compatible con los informes de pruebas de GitHub Actions, los artefactos de GitLab CI y cualquier sistema de CI que admita 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.

Formatos admitidos

Gracias a i18n-convert, el validador admite de serie 32 formatos de archivo i18n. No necesita plugins ni configuraciones específicos: detecta automáticamente el formato por la extensión y el contenido.

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

Configuración

En la mayoría de los proyectos funciona sin configuración. Si necesita más control —cambiar la gravedad de las comprobaciones, definir los idiomas esperados o excluir idiomas en curso—, cree un archivo .i18n-validate.toml en la raíz.

.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