Skip to main content

Käännösten CI-validointi: automatisoi i18n-tarkistukset putkessasi

Käännösvirheet eivät näy koodintarkistuksessa. Puuttuva avain, rikkoutunut paikkamerkki tai virheellinen monikkomuoto ei näy diffissä. CI-tason validointi löytää ne ennen tuotantoon päätymistä.

1

Miksi käännösvirheet läpäisevät koodintarkistuksen

Kehittäjä lisää en.json-tiedostoon 10 uutta avainta ja päivittää ominaisuuden koodin. PR-tarkistaja tarkistaa koodin ja englanninkieliset merkkijonot sekä hyväksyy muutoksen. Kukaan ei vertaa 14 muuta kieliversiotiedostoa. Tuotantoon päätyy kolme virhettä: de.json-tiedostosta puuttuu kaksi avainta (saksalaiset käyttäjät näkevät käsittelemättömiä avainpolkuja), fr.json-tiedoston {count}-paikkamerkki on rikkoutunut (ranskalaiset käyttäjät näkevät kirjaimellisen {count}-tekstin) ja ja.json-tiedoston ICU-monikkosyntaksi on virheellinen (japanilaisilla käyttäjillä sovellus kaatuu). Nämä voidaan estää 30 sekunnin CI-tarkistuksella.

Käännösvirheillä on ainutlaatuinen ominaisuus: ne eivät näy kehittäjälle tai tarkistajalle vaan ainoastaan tietyn kieliversion käyttäjille. CI-validointi on ainoa luotettava tapa löytää ne ennen tuotantoa.
2

Asenna i18n-validate

Lisää i18n-validate projektiisi kehitysriippuvuutena. Se tukee heti JSON-, YAML-, PO-, XLIFF- ja ARB-muotoja, eikä peruskäyttö tarvitse määrityksiä.

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

GitHub Actions -integraatio

Lisää i18n-validate pull request -työnkulkusi vaiheeksi. Työkalu päättyy virheiden löytyessä koodilla 1, jolloin PR-tarkistus epäonnistuu. Käytä JUnit XML -tulostetta testiraportoijatoiminnon kanssa saadaksesi rivinsisäiset merkinnät suoraan PR-diffiin.

.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
Kiinnitä i18n-validate:n versio työnkulussasi, jotta uudet validointisäännöt eivät aiheuta odottamattomia rikkoutumisia. Käytä @latest-versiota vain kehityksessä.
4

GitLab CI -integraatio

Lisää .gitlab-ci.yml-putkeesi käännösvalidointityö. GitLab tukee suoraan JUnit XML -artefakteja — lähetä validointiraportti, niin virheet näkyvät merge requestin Test-välilehdellä.

.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

Commitia edeltävä koukku

Saat palautetta nopeammin suorittamalla validoinnin commitia edeltävänä koukkuna. Näin ongelmat löytyvät jo ennen CI:tä, mikä säästää putken aikaa ja lyhentää palautekierroksia. Hallitse koukkuja Huskylla (JS) tai pre-commitilla (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
Commitia edeltävät koukut suoritetaan jokaisella commitilla, joten pidä ne nopeina. Validoi --locales-valitsimella kaikkien kieliversioiden sijaan vain nykyisessä commitissa muuttuneet kieliversiot. Näin koukun suoritus kestää useimmissa projekteissa alle kaksi sekuntia.
6

Määritykset ja vakavuustasot

Mukauta validointitoimintaa .i18n-validate.toml-määritystiedostolla. Aseta tarkistusten kielikohtaiset vakavuustasot (virhe, varoitus, pois), määritä odotetut kielet, jätä keskeneräiset kieliversiot pois ja määritä tulostemuoto. CI:ssä vain virheet kaatavat putken — varoitukset näkyvät raportissa mutta eivät estä.

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
}

Kokeile i18n Agent:ia nyt

Pudota käännöstiedostosi tähän

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

tai valitse napsauttamalla

Kohdekielet

Rekisteröitymistä ei tarvitaVälitön arvio

Usein kysyttyä käännösten CI-validoinnista