Skip to main content

Pengesahan Terjemahan CI: Automatikkan Pemeriksaan i18n dalam Saluran anda

Pepijat terjemahan tidak kelihatan dalam semakan kod. Kekunci yang tiada, ruang letak rosak, bentuk jamak cacat — tiada satu pun kelihatan dalam perbezaan. Pengesahan peringkat CI mengesannya sebelum mencapai pengeluaran.

1

Mengapa Pepijat Terjemahan Terlepas daripada Semakan Kod

Pembangun menambahkan 10 kekunci baharu pada en.json dan mengemas kini kod ciri. Penyemak PR memeriksa kod, mengesahkan rentetan bahasa Inggeris, dan meluluskan. Tiada sesiapa membandingkan 14 fail lokal lain. Tiga pepijat masuk ke pengeluaran: de.json tiada 2 kekunci (pengguna Jerman melihat laluan kekunci mentah), fr.json mempunyai ruang letak {count} yang rosak (pengguna Perancis melihat {count} secara literal), dan ja.json mempunyai bentuk jamak ICU yang cacat (pengguna Jepun mengalami ranap). Semua ini boleh dicegah dengan pemeriksaan CI selama 30 saat.

Pepijat terjemahan mempunyai sifat unik: tidak kelihatan kepada pembangun, tidak kelihatan kepada penyemak, dan hanya kelihatan kepada pengguna dalam lokal tertentu. Pengesahan CI ialah satu-satunya cara yang boleh dipercayai untuk mengesannya sebelum pengeluaran.
2

Pasang i18n-validate

Tambahkan i18n-validate pada projek sebagai kebergantungan pembangunan. Alat ini terus menyokong format JSON, YAML, PO, XLIFF, dan ARB — tiada konfigurasi diperlukan untuk penggunaan asas.

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

Penyepaduan GitHub Actions

Tambahkan i18n-validate sebagai langkah dalam aliran kerja pull request. Alat ini keluar dengan kod 1 apabila ralat ditemui sehingga pemeriksaan PR gagal. Gunakan output JUnit XML dengan tindakan pelapor ujian untuk mendapatkan anotasi sebaris secara langsung pada perbezaan PR.

.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
Sematkan versi i18n-validate dalam aliran kerja anda untuk mengelakkan kerosakan tidak dijangka akibat peraturan pengesahan baharu. Gunakan @latest hanya dalam pembangunan.
4

Penyepaduan GitLab CI

Tambahkan tugas pengesahan terjemahan pada saluran .gitlab-ci.yml anda. GitLab menyokong artifak JUnit XML secara natif — muat naik laporan pengesahan dan ralat akan muncul dalam tab Test pada merge request.

.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

Cangkuk Pre-Commit

Untuk maklum balas lebih pantas, jalankan pengesahan sebagai cangkuk pre-commit. Cara ini mengesan masalah sebelum mencapai CI sehingga menjimatkan masa saluran dan mengurangkan kitaran maklum balas. Gunakan Husky (JS) atau pre-commit (Python) untuk mengurus cangkuk.

.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
Cangkuk pre-commit berjalan pada setiap komit, jadi pastikan ia kekal pantas. Gunakan bendera --locales untuk hanya mengesahkan lokal yang berubah dalam komit semasa, bukan semua lokal. Cara ini memastikan pelaksanaan cangkuk di bawah 2 saat untuk kebanyakan projek.
6

Konfigurasi dan Tahap Keterukan

Sesuaikan tingkah laku pengesahan dengan fail konfigurasi .i18n-validate.toml. Tetapkan tahap keterukan pemeriksaan (error, warning, off) bagi setiap peraturan, tentukan bahasa yang dijangkakan, kecualikan lokal WIP, dan konfigurasikan format output. Dalam CI, hanya ralat yang menggagalkan saluran — amaran muncul dalam laporan, tetapi tidak menyekat.

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
}

Cuba i18n Agent Sekarang

Lepaskan fail terjemahan anda di sini

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

atau klik untuk semak imbas

Bahasa sasaran

Tidak perlu mendaftarAnggaran serta-merta

Soalan Lazim Pengesahan Terjemahan CI