Skip to main content

CI çeviri doğrulaması: işlem hattınızdaki i18n denetimlerini otomatikleştirin

Çeviri hataları kod incelemesinde görünmez. Eksik anahtar, bozuk yer tutucu veya hatalı biçimlendirilmiş çoğul ifadesi fark görünümünde ortaya çıkmaz. CI düzeyindeki doğrulama, bunları üretime ulaşmadan yakalar.

1

Çeviri hataları kod incelemesinden neden kaçar?

Bir geliştirici en.json dosyasına 10 yeni anahtar ekleyip özellik kodunu günceller. PR inceleyicisi kodu denetler, İngilizce dizeleri doğrular ve onay verir. Diğer 14 yerel ayar dosyasının farkını kimse incelemez. Üretime üç hata çıkar: de.json içinde 2 anahtar eksiktir (Almanca kullanıcılar ham anahtar yollarını görür), fr.json içinde bozuk bir {count} yer tutucusu vardır (Fransızca kullanıcılar değişmez {count} metnini görür) ve ja.json içinde hatalı biçimlendirilmiş bir ICU çoğul ifadesi bulunur (Japonca kullanıcılar çökmeyle karşılaşır). Bunlar 30 saniyelik bir CI denetimiyle önlenebilir.

Çeviri hatalarının benzersiz bir özelliği vardır: geliştirici ve inceleyici tarafından görülmez, yalnızca belirli bir yerel ayarı kullanan kullanıcılar tarafından görülür. CI doğrulaması, bunları üretimden önce yakalamanın tek güvenilir yoludur.
2

i18n-validate'i yükleyin

i18n-validate'i projenize geliştirme bağımlılığı olarak ekleyin. JSON, YAML, PO, XLIFF ve ARB biçimlerini kullanıma hazır olarak destekler; temel kullanım için yapılandırma gerekmez.

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

GitHub Actions bütünleştirmesi

i18n-validate'i çekme isteği iş akışınıza bir adım olarak ekleyin. Araç hata bulduğunda 1 koduyla çıkar ve PR denetiminin başarısız olmasını sağlar. Satır içi açıklamaları doğrudan PR farkında görmek için bir test raporlayıcı eylemiyle JUnit XML çıktısını kullanın.

.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
Yeni doğrulama kurallarından kaynaklanan beklenmedik bozulmaları önlemek için iş akışınızda i18n-validate sürümünü sabitleyin. @latest sürümünü yalnızca geliştirme ortamında kullanın.
4

GitLab CI bütünleştirmesi

.gitlab-ci.yml işlem hattınıza bir çeviri doğrulama işi ekleyin. GitLab, JUnit XML yapıtlarını yerel olarak destekler; doğrulama raporunu yüklediğinizde hatalar birleştirme isteğinin Test sekmesinde görünür.

.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

Ön işleme kancası

Daha hızlı geri bildirim için doğrulamayı ön işleme kancası olarak çalıştırın. Bu yöntem sorunları CI'a ulaşmadan yakalayarak işlem hattı süresinden tasarruf eder ve geri bildirim döngülerini kısaltır. Kancaları yönetmek için Husky (JS) veya pre-commit (Python) kullanın.

.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
Ön işleme kancaları her işlemede çalıştığından hızlı olmalarını sağlayın. Tüm yerel ayarlar yerine yalnızca geçerli işlemede değişen yerel ayarları doğrulamak için --locales bayrağını kullanın. Böylece çoğu projede kancanın çalışma süresi 2 saniyenin altında kalır.
6

Yapılandırma ve önem düzeyleri

Doğrulama davranışını .i18n-validate.toml yapılandırma dosyasıyla özelleştirin. Her kural için denetim önemini (error, warning, off) belirleyin, beklenen dilleri tanımlayın, devam eden yerel ayarları hariç tutun ve çıktı biçimini yapılandırın. CI'da yalnızca hatalar işlem hattını başarısız kılar; uyarılar raporda görünür ancak engel oluşturmaz.

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
}

i18n Agent'ı şimdi deneyin

Çeviri dosyanızı buraya bırakın

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

veya göz atmak için tıklayın

Hedef diller

Kayıt gerekmezAnında fiyat tahmini

CI çeviri doğrulaması hakkında sık sorulan sorular