Skip to main content

CI-validering av oversettelser: Automatiser i18n-kontroller i prosessen

Oversettelsesfeil er usynlige under kodegjennomgang. En manglende nøkkel, en ødelagt plassholder eller en feilformatert flertallsform – ingen av disse vises i en diff. Validering på CI-nivå finner dem før de når produksjon.

1

Hvorfor oversettelsesfeil slipper gjennom kodegjennomgangen

En utvikler legger til 10 nye nøkler i en.json og oppdaterer funksjonskoden. Den som gjennomgår PR-en, går gjennom koden, verifiserer de engelske strengene og godkjenner. Ingen sammenligner de 14 andre språkfilene. Tre feil rulles ut i produksjon: de.json mangler 2 nøkler (tyske brukere ser rå nøkkelstier), fr.json har en ødelagt {count}-plassholder (franske brukere ser den bokstavelige teksten {count}), og ja.json har en feilformatert ICU-flertallsform (japanske brukere opplever et krasj). Disse feilene kan forhindres med en CI-kontroll på 30 sekunder.

Oversettelsesfeil har en unik egenskap: De er usynlige for utvikleren og den som gjennomgår koden, og bare synlige for brukere med en bestemt språkvariant. CI-validering er den eneste pålitelige måten å finne dem på før produksjon.
2

Installer i18n-validate

Legg til i18n-validate som utviklingsavhengighet i prosjektet. Det støtter JSON-, YAML-, PO-, XLIFF- og ARB-formater direkte – grunnleggende bruk krever ingen konfigurasjon.

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

Integrasjon med GitHub Actions

Legg til i18n-validate som et trinn i arbeidsflyten for pull requests. Verktøyet avsluttes med kode 1 når det finner feil, slik at PR-kontrollen mislykkes. Bruk JUnit XML-resultater sammen med en testrapporterings-action for å få integrerte merknader direkte i PR-diffen.

.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
Lås versjonen av i18n-validate i arbeidsflyten for å unngå uventede brudd fra nye valideringsregler. Bruk @latest bare under utvikling.
4

Integrasjon med GitLab CI

Legg til en jobb for validering av oversettelser i .gitlab-ci.yml-prosessen. GitLab støtter JUnit XML-artefakter direkte – last opp valideringsrapporten, så vises feilene i Test-fanen i forespørselen om sammenslåing.

.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

Kjør valideringen som en pre-commit-hook for å få raskere tilbakemelding. Dette finner problemer før de når CI, sparer tid i prosessen og forkorter tiden frem til tilbakemelding. Bruk Husky (JS) eller pre-commit (Python) til å administrere hookene.

.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-kroker kjøres ved hver innsjekking, så sørg for at de er raske. Bruk flagget --locales for å validere bare språkvariantene som er endret i den gjeldende innsjekkingen, i stedet for alle språkvariantene. Dette holder krokenes kjøretid under 2 sekunder for de fleste prosjekter.
6

Konfigurasjon og alvorlighetsgrader

Tilpass valideringen med konfigurasjonsfilen .i18n-validate.toml. Angi alvorlighetsgrad for hver regel (error, warning, off), definer forventede språk, utelat språkvarianter som er under arbeid, og konfigurer utdataformatet. I CI er det bare feil som får prosessen til å mislykkes – advarsler vises i rapporten, men blokkerer ikke.

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
}

Prøv i18n Agent nå

Slipp oversettelsesfilen din her

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

eller klikk for å bla gjennom

Målspråk

Ingen registrering krevesUmiddelbart estimat

Vanlige spørsmål om CI-validering av oversettelser