Skip to main content

Översättningsvalidering i CI: automatisera i18n-kontroller i processen

Översättningsfel syns inte vid kodgranskning. En saknad nyckel, en trasig platshållare eller en felaktigt formaterad pluralform syns inte i en diff. Validering på CI-nivå upptäcker dem innan de når produktion.

1

Därför missas översättningsfel vid kodgranskning

En utvecklare lägger till 10 nya nycklar i en.json och uppdaterar funktionskoden. PR-granskaren kontrollerar koden, verifierar de engelska strängarna och godkänner ändringen. Ingen jämför de 14 andra språkfilerna. Tre fel når produktion: de.json saknar 2 nycklar (tyska användare ser obearbetade nyckelsökvägar), fr.json har en trasig {count}-platshållare (franska användare ser den bokstavliga texten {count}) och ja.json har en felaktigt formaterad ICU-pluralform (japanska användare möts av en krasch). De här felen kan förhindras med en CI-kontroll på 30 sekunder.

Översättningsfel har en särskild egenskap: de är osynliga för utvecklaren och granskaren och syns bara för användare med ett visst språk. CI-validering är det enda tillförlitliga sättet att upptäcka dem före produktion.
2

Installera i18n-validate

Lägg till i18n-validate i projektet som ett utvecklingsberoende. Det stöder JSON, YAML, PO, XLIFF och ARB direkt. Ingen konfiguration behövs för grundläggande användning.

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

Integrering med GitHub Actions

Lägg till i18n-validate som ett steg i arbetsflödet för pull requests. Verktyget avslutas med kod 1 när fel hittas, vilket gör att PR-kontrollen misslyckas. Använd JUnit XML-utdata med en åtgärd för testrapportering för att få infogade kommentarer direkt 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 versionen av i18n-validate i arbetsflödet för att undvika oväntade problem till följd av nya valideringsregler. Använd bara @latest under utveckling.
4

Integrering med GitLab CI

Lägg till ett jobb för översättningsvalidering i .gitlab-ci.yml-processen. GitLab har inbyggt stöd för JUnit XML-artefakter. Ladda upp valideringsrapporten, så visas felen på fliken Test i merge requesten.

.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-krok

Kör valideringen som en pre-commit-krok för att få snabbare återkoppling. Då upptäcks problem redan innan de når CI, vilket sparar processtid och förkortar återkopplingscyklerna. Hantera krokarna med Husky (JS) eller 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-krokar körs vid varje commit, så se till att de är snabba. Använd flaggan --locales för att bara validera de språk som ändrades i den aktuella committen i stället för alla språk. Då tar körningen mindre än 2 sekunder för de flesta projekt.
6

Konfiguration och allvarlighetsgrader

Anpassa valideringsbeteendet med konfigurationsfilen .i18n-validate.toml. Ange allvarlighetsgrad (error, warning, off) per regel, definiera förväntade språk, uteslut pågående översättningar och konfigurera utdataformatet. I CI är det bara errors som får processen att misslyckas. Warnings visas i rapporten, men blockerar inte.

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
}

Prova i18n Agent nu

Släpp din översättningsfil här

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

eller klicka för att välja en fil

Målspråk

Ingen registrering krävsPrisuppskattning direkt

Vanliga frågor om översättningsvalidering i CI