Skip to main content

Validation des traductions en CI : automatisez les contrôles i18n dans votre pipeline

Les bugs de traduction sont invisibles en revue de code. Une clé manquante, un espace réservé cassé, un pluriel malformé : rien de tout cela n'apparaît dans un diff. La validation au niveau de la CI les détecte avant qu'ils n'atteignent la production.

1

Pourquoi les bugs de traduction passent inaperçus en revue de code

Un développeur ajoute 10 nouvelles clés à en.json et met à jour le code de la fonctionnalité. Le relecteur de la PR vérifie le code, contrôle les chaînes en anglais, et approuve. Personne ne compare les 14 autres fichiers de locale. Trois bugs partent en production : de.json manque 2 clés (les utilisateurs allemands voient les chemins de clés bruts), fr.json a un espace réservé {count} cassé (les utilisateurs français voient littéralement {count}), et ja.json a un pluriel ICU malformé (les utilisateurs japonais voient un plantage). Ces problèmes sont évitables avec un contrôle CI de 30 secondes.

Les bugs de traduction ont une particularité : ils sont invisibles pour le développeur, invisibles pour le relecteur, et ne sont visibles que par les utilisateurs d'une locale spécifique. La validation en CI est le seul moyen fiable de les détecter avant la production.
2

Installer i18n-validate

Ajoutez i18n-validate à votre projet en tant que dépendance de développement. Il prend en charge nativement les formats JSON, YAML, PO, XLIFF et ARB : aucune configuration n'est nécessaire pour un usage basique.

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

Intégration avec GitHub Actions

Ajoutez i18n-validate comme étape dans votre flux de travail de pull request. L'outil se termine avec le code 1 en cas d'erreurs détectées, faisant échouer le contrôle de la PR. Utilisez la sortie JUnit XML avec une action de type test reporter pour obtenir des annotations en ligne directement sur le diff de la PR.

.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
Figez la version d'i18n-validate dans votre flux de travail pour éviter les ruptures inattendues dues à de nouvelles règles de validation. N'utilisez @latest qu'en développement.
4

Intégration avec GitLab CI

Ajoutez un job de validation des traductions à votre pipeline .gitlab-ci.yml. GitLab prend nativement en charge les artefacts JUnit XML : téléversez le rapport de validation, et les erreurs apparaissent dans l'onglet Test de la merge request.

.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

Pour un retour plus rapide, exécutez la validation en tant que hook pre-commit. Cela détecte les problèmes avant même qu'ils n'atteignent la CI, ce qui économise du temps de pipeline et réduit les boucles de retour. Utilisez Husky (JS) ou pre-commit (Python) pour gérer les 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
Les hooks pre-commit s'exécutent à chaque commit, il faut donc les garder rapides. Utilisez le flag --locales pour ne valider que les locales modifiées dans le commit en cours, plutôt que toutes les locales. Cela permet de garder l'exécution du hook sous les 2 secondes pour la plupart des projets.
6

Configuration et niveaux de sévérité

Personnalisez le comportement de la validation avec un fichier de configuration .i18n-validate.toml. Définissez la sévérité de chaque contrôle (error, warning, off) par règle, définissez les langues attendues, excluez les locales en cours de travail (WIP), et configurez le format de sortie. En CI, seules les erreurs font échouer le pipeline : les avertissements apparaissent dans le rapport mais ne bloquent rien.

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
}

Essayez i18n Agent maintenant

Déposez votre fichier de traduction ici

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

ou cliquez pour parcourir

Langues cibles

Aucune inscription requiseEstimation instantanée

FAQ validation des traductions en CI