i18n-validate kiểm tra những gì?

Công cụ chạy 9 phép kiểm tra: khóa bị thiếu, khóa dư thừa, placeholder bị hỏng, dạng số nhiều sai cấu trúc, ngôn ngữ bị thiếu, ngôn ngữ mồ côi, lỗi phân tích cú pháp, giá trị trống và chuỗi chưa dịch. Với từng ngôn ngữ, bạn có thể đặt mỗi phép kiểm tra thành lỗi, cảnh báo hoặc tắt.

Làm cách nào để thêm bước xác thực bản dịch vào CI/CD?

Chạy 'npx @i18n-agent/i18n-validate ./locales --format junit -o i18n-report.xml' trong pipeline. Khi tìm thấy lỗi, công cụ thoát với mã 1 và khiến CI thất bại theo cơ chế thông thường. Dùng đầu ra JUnit XML với các action báo cáo kiểm thử để thêm chú thích ngay trong PR.

Công cụ hỗ trợ những định dạng tệp bản dịch nào?

Công cụ hỗ trợ 32 định dạng, gồm JSON, YAML, XLIFF 1.2/2.0, Android XML, iOS Strings, iOS Stringsdict, Xcode String Catalogs, Flutter ARB, Gettext PO, Java Properties, .NET RESX, PHP/Laravel, CSV, Excel và nhiều định dạng khác. Công cụ tự động phát hiện định dạng từ phần mở rộng tệp.

Open Source CLI Tool

i18n Validator

Name: i18n Agent
Price: 0.01 EUR
Author: i18n Agent

Kiểm tra tệp bản dịch để tìm khóa bị thiếu, placeholder bị hỏng và dạng số nhiều không nhất quán. Một lệnh. 9 phép kiểm tra. 32 định dạng. Không cần cấu hình.

9 checks 32 formats Zero config Native Rust binary

Vấn đề

Bạn không thể nhận ra lỗi bản dịch cho đến khi người dùng gặp phải. Khóa bị thiếu sẽ hiển thị đường dẫn thô như "settings.billing.title" thay vì văn bản thực. Placeholder bị hỏng sẽ hiển thị "{price}" dưới dạng văn bản nguyên trạng thay vì "250.000₫". Dạng số nhiều sai cấu trúc sẽ khiến ứng dụng gặp sự cố khi số lượng bằng không. Những lỗi này lọt qua bước đánh giá mã vì không ai so sánh thủ công 15 tệp ngôn ngữ.

🔑

Missing keys

Blank text or key paths shown to users

🔗

Broken placeholders

{price} displays as literal text instead of $9.99

📁

Orphaned files

Outdated translations confuse the build system

💥

Malformed files

Runtime crashes when users switch languages

Hầu hết công cụ xác thực chỉ hỗ trợ một định dạng cụ thể (chỉ JSON hoặc chỉ YAML) và đòi hỏi mã kiểm thử tùy chỉnh cho từng dự án. Lỗi bản dịch thường chỉ bị phát hiện khi chạy, lúc người dùng nhìn thấy giao diện bị lỗi.

Giải pháp

i18n-validate quét toàn bộ tệp bản dịch của bạn trong một lượt. Công cụ tự động phát hiện cấu trúc thư mục và định dạng tệp, so sánh từng ngôn ngữ với bản tham chiếu rồi báo chính xác lỗi nằm ở đâu và là lỗi gì. Không cần plugin, cấu hình hay mã kiểm thử tùy chỉnh.

Check	Severity	What it catches
missing-keys	error	Key exists in reference but is absent in a translation
extra-keys	error	Key exists in translation but not in the reference
placeholders	error	{price}, {{name}}, %s differ between languages
plural-structure	error	Plural forms are malformed or missing required categories
missing-languages	error	Expected language has no files or directory
orphaned-languages	error	Language files exist but are not in the expected list
parse-errors	error	File fails to parse (broken JSON, XML, YAML, etc.)
empty-values	warning	Key is present but the translation is an empty string
untranslated	warning	Translation is identical to the reference language

Terminal output

i18n-validate v0.1.0 — validating ./locales

  Reference: en (2 files: translation.json, apiTester.json)
  Languages: de, ja, fr, es, zh-Hans, pt-BR, ko (7 found, 7 expected)
  Layout   : directory (auto-detected)
  Formats  : i18next JSON (auto-detected)

────────────────────────────────────────────────

ERRORS (5)

  ✗ missing-keys │ translation.json
    Key "settings.billing.title"
      missing in: ja, ko

  ✗ placeholders │ translation.json
    Key "pricing.total" — expected: {price}, {currency}
      de:  found {price} only — missing {currency}

────────────────────────────────────────────────

WARNINGS (2)

  ⚠ empty-values │ translation.json
    Key "onboarding.step3.hint"
      empty in: de, fr

────────────────────────────────────────────────

  5 errors, 2 warnings across 7 languages
  ✗ Validation failed

Cài đặt

Cài đặt dưới dạng công cụ CLI toàn cục bằng trình quản lý gói bạn thường dùng. Gói npm tích hợp sẵn tệp nhị phân Rust gốc nên không cần biên dịch hay phụ thuộc khi chạy.

Terminal

npm install -g @i18n-agent/i18n-validate

Gói npm tích hợp sẵn tệp nhị phân gốc đã biên dịch cho macOS, Linux và Windows. Bạn không cần bộ công cụ Rust.

Cách dùng

Trỏ công cụ đến thư mục ngôn ngữ của bạn. Công cụ tự động phát hiện ngôn ngữ tham chiếu, cấu trúc thư mục và định dạng tệp. Hầu hết dự án không cần cấu hình.

Terminal

# Zero-config validation
i18n-validate ./locales

# JSON output for scripting
i18n-validate ./locales --format json | jq '.summary'

# CI/CD with JUnit XML
i18n-validate ./locales --format junit -o i18n-report.xml

Tích hợp CI/CD

Thêm bước xác thực bản dịch vào pipeline pull request. Công cụ xuất JUnit XML, tương thích với trình báo cáo kiểm thử của GitHub Actions, artifact của GitLab CI và mọi hệ thống CI hỗ trợ JUnit.

.github/workflows/validate-i18n.yml

name: Validate Translations
on:
  pull_request:
    paths: ['locales/**', 'public/locales/**']

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Validate translations
        run: npx @i18n-agent/i18n-validate ./locales --format junit -o i18n-report.xml

      - uses: dorny/test-reporter@v1
        if: always()
        with:
          name: i18n validation
          path: i18n-report.xml
          reporter: java-junit

The tool exits with code 1 when errors are found, so it naturally fails CI. Use --strict to also fail on warnings.

Định dạng được hỗ trợ

Nhờ i18n-convert, trình xác thực hỗ trợ sẵn 32 định dạng tệp i18n. Bạn không cần plugin hay cấu hình riêng cho từng định dạng vì công cụ tự động phát hiện định dạng từ phần mở rộng và nội dung tệp.

Mobile & Desktop

Android XML, Xcode String Catalog, iOS Strings, iOS Stringsdict, Flutter ARB, Qt Linguist

Web & Frameworks

Structured JSON, i18next JSON, JSON5, HJSON, YAML (Rails), YAML (Plain), JavaScript, TypeScript, PHP/Laravel, NEON

Standards & Exchange

XLIFF 1.2, XLIFF 2.0, Gettext PO, TMX, .NET RESX, Java Properties

Data & Other

CSV, Excel (.xlsx), TOML, INI, SRT Subtitles, Markdown, Plain Text

Cấu hình

Hầu hết dự án không cần cấu hình. Khi cần kiểm soát chi tiết như thay đổi mức độ nghiêm trọng của phép kiểm tra, đặt danh sách ngôn ngữ dự kiến hoặc loại trừ ngôn ngữ đang hoàn thiện, hãy tạo tệp .i18n-validate.toml tại thư mục gốc của dự án.

.i18n-validate.toml

# .i18n-validate.toml
ref = "en"
expect = ["de", "ja", "fr", "es", "zh-Hans", "pt-BR", "ko"]

[checks]
missing-keys = "error"
extra-keys = "error"
placeholders = "error"
empty-values = "warning"
untranslated = "warning"

[languages.ko]
missing-keys = "warning"    # Korean is WIP

[languages.ar]
skip = true                 # Exclude from validation