Skip to main content

Validasi Terjemahan CI: Otomatiskan Pemeriksaan i18n dalam Pipeline Anda

Bug terjemahan tidak terlihat dalam peninjauan kode. Kunci yang tidak tersedia, placeholder rusak, bentuk jamak yang cacat — tidak satu pun terlihat dalam diff. Validasi tingkat CI menemukannya sebelum mencapai produksi.

1

Mengapa Bug Terjemahan Lolos dari Peninjauan Kode

Developer menambahkan 10 kunci baru ke en.json dan memperbarui kode fitur. Peninjau PR memeriksa kode, memverifikasi string bahasa Inggris, dan menyetujui. Tidak ada yang membandingkan 14 file locale lainnya. Tiga bug masuk ke produksi: de.json tidak memiliki 2 kunci (pengguna Jerman melihat jalur kunci mentah), fr.json memiliki placeholder {count} yang rusak (pengguna Prancis melihat {count} secara literal), dan ja.json memiliki bentuk jamak ICU yang cacat (pengguna Jepang mengalami crash). Semua ini dapat dicegah dengan pemeriksaan CI selama 30 detik.

Bug terjemahan memiliki sifat unik: tidak terlihat oleh developer, tidak terlihat oleh peninjau, dan hanya terlihat oleh pengguna dalam locale tertentu. Validasi CI adalah satu-satunya cara andal untuk menemukannya sebelum produksi.
2

Instal i18n-validate

Tambahkan i18n-validate ke proyek sebagai dependensi pengembangan. Alat ini langsung mendukung format JSON, YAML, PO, XLIFF, dan ARB — tidak diperlukan konfigurasi untuk penggunaan dasar.

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

Integrasi GitHub Actions

Tambahkan i18n-validate sebagai langkah dalam alur kerja pull request. Alat ini keluar dengan kode 1 ketika kesalahan ditemukan sehingga pemeriksaan PR gagal. Gunakan keluaran JUnit XML dengan action pelapor pengujian untuk mendapatkan anotasi inline langsung pada diff 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 alur kerja Anda untuk menghindari kerusakan tak terduga akibat aturan validasi baru. Gunakan @latest hanya dalam pengembangan.
4

Integrasi GitLab CI

Tambahkan job validasi terjemahan ke pipeline .gitlab-ci.yml Anda. GitLab mendukung artefak JUnit XML secara native — unggah laporan validasi dan kesalahan akan muncul di 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

Hook Pre-Commit

Untuk umpan balik lebih cepat, jalankan validasi sebagai hook pre-commit. Cara ini menemukan masalah sebelum mencapai CI sehingga menghemat waktu pipeline dan mengurangi siklus umpan balik. Gunakan Husky (JS) atau pre-commit (Python) untuk mengelola hook.

.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
Hook pre-commit berjalan pada setiap commit, jadi pastikan tetap cepat. Gunakan flag --locales untuk hanya memvalidasi locale yang berubah dalam commit saat ini, bukan semua locale. Cara ini menjaga eksekusi hook di bawah 2 detik untuk sebagian besar proyek.
6

Konfigurasi dan Tingkat Keparahan

Sesuaikan perilaku validasi dengan file konfigurasi .i18n-validate.toml. Atur tingkat keparahan pemeriksaan (error, warning, off) per aturan, tentukan bahasa yang diharapkan, kecualikan locale WIP, dan konfigurasikan format keluaran. Di CI, hanya kesalahan yang menggagalkan pipeline — peringatan muncul dalam laporan, tetapi tidak memblokir.

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
}

Coba i18n Agent Sekarang

Lepaskan file terjemahan Anda di sini

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

atau klik untuk menjelajahi

Bahasa target

Tidak perlu mendaftarEstimasi instan

Tanya Jawab Validasi Terjemahan CI