Skip to main content

CI-vertaalvalidatie: automatiseer i18n-controles in je pipeline

Vertaalfouten zijn onzichtbaar bij een codebeoordeling. Een ontbrekende sleutel, een defecte placeholder, een onjuist opgebouwde meervoudsvorm: geen van deze fouten is zichtbaar in een diff. Validatie op CI-niveau onderschept ze voordat ze in productie belanden.

1

Waarom vertaalfouten bij codebeoordelingen onopgemerkt blijven

Een ontwikkelaar voegt 10 nieuwe sleutels toe aan en.json en werkt de code voor de functie bij. De PR-beoordelaar controleert de code en de Engelse teksten en keurt alles goed. Niemand vergelijkt de 14 andere localebestanden. Zo belanden er drie fouten in productie: in de.json ontbreken 2 sleutels (Duitse gebruikers zien onbewerkte sleutelpaden), fr.json bevat een defecte placeholder {count} (Franse gebruikers zien letterlijk {count}) en ja.json bevat een onjuist opgebouwde ICU-meervoudsvorm (de app crasht bij Japanse gebruikers). Met een CI-controle van 30 seconden kun je dit voorkomen.

Vertaalfouten hebben een unieke eigenschap: ze zijn onzichtbaar voor de ontwikkelaar en de beoordelaar en alleen zichtbaar voor gebruikers met een specifieke locale. CI-validatie is de enige betrouwbare manier om ze vóór productie te onderscheppen.
2

i18n-validate installeren

Voeg i18n-validate als ontwikkelafhankelijkheid toe aan je project. Het ondersteunt standaard de indelingen JSON, YAML, PO, XLIFF en ARB. Voor basisgebruik is geen configuratie nodig.

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

Integratie met GitHub Actions

Voeg i18n-validate als stap toe aan je workflow voor pullrequests. Als er fouten worden gevonden, wordt het hulpprogramma afgesloten met code 1 en mislukt de PR-controle. Gebruik JUnit XML-uitvoer met een actie voor testrapportage om rechtstreeks in de PR-diff inline annotaties weer te geven.

.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
Zet de versie van i18n-validate vast in je workflow om onverwachte problemen door nieuwe validatieregels te voorkomen. Gebruik @latest alleen tijdens de ontwikkeling.
4

Integratie met GitLab CI

Voeg een taak voor vertaalvalidatie toe aan de pipeline in .gitlab-ci.yml. GitLab biedt ingebouwde ondersteuning voor JUnit XML-artefacten. Upload het validatierapport, waarna de fouten op het tabblad Test van de mergerequest verschijnen.

.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

Pre-commit-hook

Voer de validatie als pre-commit-hook uit om sneller feedback te krijgen. Zo onderschep je problemen nog voordat ze CI bereiken, bespaar je pipelinetijd en verkort je de feedbackcyclus. Beheer hooks met Husky (JS) of pre-commit (Python).

.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
Pre-commit-hooks worden bij elke commit uitgevoerd, dus zorg dat ze snel blijven. Gebruik de vlag --locales om alleen de locales te valideren die in de huidige commit zijn gewijzigd en niet alle locales. Zo duurt de hook bij de meeste projecten minder dan 2 seconden.
6

Configuratie en ernstniveaus

Pas het validatiegedrag aan met een configuratiebestand genaamd .i18n-validate.toml. Stel per regel het ernstniveau (error, warning, off) in, definieer de verwachte talen, sluit WIP-locales uit en configureer de uitvoerindeling. In CI laten alleen fouten de pipeline mislukken. Waarschuwingen verschijnen wel in het rapport, maar blokkeren de pipeline niet.

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
}

Probeer i18n Agent nu

Zet je vertaalbestand hier neer

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

of klik om een bestand te selecteren

Doeltalen

Geen registratie nodigDirecte prijsindicatie

Veelgestelde vragen over CI-vertaalvalidatie