Skip to main content

Validación de traducciones en CI: automatice las comprobaciones de i18n

Los errores de traducción son invisibles al revisar código. Una clave ausente, un marcador roto o un plural mal formado no aparecen en las diferencias. Validarlos en CI los detecta antes de producción.

1

Por qué los errores de traducción escapan a la revisión

Un desarrollador añade 10 claves a en.json y actualiza la funcionalidad. El revisor comprueba el código y el inglés y aprueba. Nadie compara los otros 14 archivos. Tres errores llegan a producción: a de.json le faltan 2 claves —los usuarios alemanes ven rutas—, fr.json tiene un marcador {count} roto —los franceses ven {count} literal— y ja.json un plural ICU mal formado —los japoneses sufren un bloqueo—. Una comprobación de CI de 30 segundos puede evitarlos.

Los errores de traducción tienen una propiedad única: son invisibles para desarrolladores y revisores, y solo los ven usuarios de una configuración concreta. Validar en CI es la única forma fiable de detectarlos antes de producción.
2

Instalar i18n-validate

Añada i18n-validate al proyecto como dependencia de desarrollo. Admite de serie JSON, YAML, PO, XLIFF y ARB, sin configuración para el uso básico.

Terminal
npm install --save-dev @anthropic/i18n-validate
3

Integración con GitHub Actions

Añada i18n-validate como paso del flujo de solicitudes de incorporación. La herramienta termina con el código 1 si encuentra errores y hace fallar la comprobación. Utilice la salida XML JUnit con una acción de informes para obtener anotaciones directamente en las diferencias.

.github/workflows/i18n-validate.yml
# .github/workflows/i18n-validate.yml
name: Validate Translations

on:
  pull_request:
    paths:
      - 'src/locales/**'
      - 'public/locales/**'

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

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install dependencies
        run: npm ci

      - name: Validate translation files
        run: npx i18n-validate \
          --source src/locales/en.json \
          --targets 'src/locales/*.json' \
          --check-missing \
          --check-unused \
          --check-placeholders \
          --check-plurals \
          --min-coverage 95 \
          --junit-output reports/i18n.xml

      - name: Upload report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: i18n-validation-report
          path: reports/i18n.xml
Fije la versión de i18n-validate en el flujo para evitar fallos inesperados por reglas nuevas. Utilice @latest solo durante el desarrollo.
4

Integración con GitLab CI

Añada un trabajo de validación a .gitlab-ci.yml. GitLab admite de forma nativa artefactos XML JUnit: cargue el informe y los errores aparecerán en la pestaña Tests de la solicitud de fusión.

.gitlab-ci.yml
# .gitlab-ci.yml
i18n-validate:
  stage: test
  image: node:20
  script:
    - npm ci
    - npx i18n-validate \
        --source src/locales/en.json \
        --targets 'src/locales/*.json' \
        --check-missing \
        --check-unused \
        --check-placeholders \
        --min-coverage 95 \
        --junit-output reports/i18n.xml
  artifacts:
    reports:
      junit: reports/i18n.xml
  only:
    changes:
      - src/locales/**/*
5

Hook pre-commit

Para recibir información antes, ejecute la validación como hook pre-commit. Detecta problemas incluso antes de CI, ahorra tiempo de proceso y acorta los ciclos de respuesta. Utilice Husky —JS— o pre-commit —Python— para gestionar hooks.

.husky/pre-commit
# .husky/pre-commit
#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

# Only validate if translation files changed
CHANGED_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -E '(locales|i18n|translations)/')

if [ -n "$CHANGED_FILES" ]; then
  echo "Translation files changed, validating..."
  npx i18n-validate \
    --source src/locales/en.json \
    --targets 'src/locales/*.json' \
    --check-missing \
    --check-placeholders
fi
Los hooks se ejecutan en cada confirmación, así que deben ser rápidos. Utilice --locales para validar solo las configuraciones modificadas en vez de todas. En la mayoría de los proyectos, la ejecución se mantiene por debajo de 2 segundos.
6

Configuración y niveles de gravedad

Personalice el comportamiento mediante .i18n-validate.toml. Defina la gravedad —error, warning u off— por regla, los idiomas esperados, las regiones en curso que debe excluir y el formato de salida. En CI solo los errores hacen fallar el proceso; las advertencias aparecen en el informe sin bloquear.

i18n-validate.config.json
// i18n-validate.config.json
{
  "source": "src/locales/en.json",
  "targets": "src/locales/*.json",
  "checks": {
    "missing": true,         // Keys in source missing from target
    "unused": true,          // Keys in target not in source
    "placeholders": true,    // Mismatched {variables}
    "plurals": true,         // Missing CLDR plural forms
    "icu": true,             // ICU syntax validation
    "emptyValues": true,     // Empty string values
    "duplicateValues": false // Same value as source (untranslated)
  },
  "minCoverage": 95,
  "exclude": [
    "src/locales/pseudo.json"
  ],
  "junitOutput": "reports/i18n.xml",
  "format": "json"          // json | yaml | po | xliff
}

Pruebe i18n Agent ahora

Arrastre y suelte aquí su archivo de traducción

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

o haga clic para seleccionar

Idiomas de destino

No es necesario registrarsePresupuesto al instante

Preguntas frecuentes sobre validación de traducciones en CI