Skip to main content

Xác thực bản dịch trong CI: Tự động hóa quy trình kiểm tra i18n

Lỗi bản dịch không thể hiện trong quá trình duyệt mã. Khóa bị thiếu, phần giữ chỗ bị hỏng hay dạng số nhiều sai định dạng đều không xuất hiện trong diff. Quy trình xác thực ở cấp CI sẽ phát hiện các lỗi này trước khi chúng lên môi trường production.

1

Vì sao lỗi bản dịch lọt qua bước duyệt mã

Một lập trình viên thêm 10 khóa mới vào en.json và cập nhật mã của tính năng. Người duyệt PR kiểm tra mã, xác minh các chuỗi tiếng Anh rồi phê duyệt. Không ai so sánh diff của 14 tệp locale còn lại. Ba lỗi được đưa lên môi trường production: de.json thiếu 2 khóa (người dùng tiếng Đức thấy đường dẫn khóa thô), fr.json có phần giữ chỗ {count} bị hỏng (người dùng tiếng Pháp thấy nguyên văn {count}) và ja.json có dạng số nhiều ICU sai định dạng (người dùng tiếng Nhật gặp sự cố ứng dụng). Bạn có thể ngăn các lỗi này bằng một lần kiểm tra CI trong 30 giây.

Lỗi bản dịch có một đặc điểm riêng: lập trình viên và người duyệt đều không nhìn thấy lỗi, chỉ người dùng của một locale cụ thể mới thấy. Xác thực trong CI là cách đáng tin cậy duy nhất để phát hiện lỗi trước khi lên môi trường production.
2

Cài đặt i18n-validate

Thêm i18n-validate vào dự án dưới dạng phần phụ thuộc phát triển. Công cụ hỗ trợ sẵn các định dạng JSON, YAML, PO, XLIFF và ARB nên bạn không cần cấu hình khi sử dụng cơ bản.

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

Tích hợp GitHub Actions

Thêm i18n-validate làm một bước trong quy trình pull request. Khi phát hiện lỗi, công cụ thoát với mã 1 và khiến bước kiểm tra PR thất bại. Kết hợp đầu ra JUnit XML với một action báo cáo kiểm thử để nhận chú thích trực tiếp trên diff của 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
Cố định phiên bản i18n-validate trong quy trình để tránh gián đoạn bất ngờ do quy tắc xác thực mới. Chỉ dùng @latest trong môi trường phát triển.
4

Tích hợp GitLab CI

Thêm job xác thực bản dịch vào pipeline .gitlab-ci.yml. GitLab hỗ trợ sẵn artifact JUnit XML. Khi bạn tải báo cáo xác thực lên, lỗi sẽ xuất hiện trong thẻ Test của 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

Để nhận phản hồi nhanh hơn, hãy chạy quy trình xác thực dưới dạng hook pre-commit. Cách này phát hiện lỗi trước cả khi chúng đến CI, giúp tiết kiệm thời gian chạy pipeline và rút ngắn vòng lặp phản hồi. Dùng Husky (JS) hoặc pre-commit (Python) để quản lý 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 chạy ở mỗi commit nên cần bảo đảm tốc độ nhanh. Dùng cờ --locales để chỉ xác thực các locale thay đổi trong commit hiện tại thay vì tất cả locale. Nhờ đó, hook chạy trong chưa đến 2 giây ở hầu hết dự án.
6

Cấu hình và mức độ nghiêm trọng

Tùy chỉnh cách xác thực bằng tệp cấu hình .i18n-validate.toml. Đặt mức độ nghiêm trọng (error, warning, off) cho từng quy tắc, xác định các ngôn ngữ cần có, loại trừ locale WIP và cấu hình định dạng đầu ra. Trong CI, chỉ error mới khiến pipeline thất bại. Warning xuất hiện trong báo cáo nhưng không chặn pipeline.

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
}

Dùng thử i18n Agent ngay

Thả tệp bản dịch của bạn vào đây

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

hoặc nhấp để duyệt

Ngôn ngữ đích

Không cần đăng kýBáo giá tức thì

Câu hỏi thường gặp về xác thực bản dịch trong CI