Chuyển đến nội dung chính

Cookbook: Dịch 30 ngôn ngữ

Mở rộng dự án từ một vài ngôn ngữ sang phạm vi toàn cầu. Cookbook này sẽ hướng dẫn bạn cách chọn phương pháp, tối ưu chi phí và tích hợp CI cho một đợt triển khai đa ngôn ngữ thực tế.

Tình huống: Bạn có một ứng dụng SaaS với en, fr, es. Bạn cần thêm 27 ngôn ngữ nữa với ba cấp độ yêu cầu chất lượng khác nhau.

Bước 1: Phân loại ngôn ngữ của bạn​

Không phải cả 30 ngôn ngữ đều cần cùng một cách tiếp cận. Hãy nhóm chúng lại dựa trên chất lượng của phương pháp có sẵn:

Cấp độNgôn ngữPhương phápLý do
Cấp độ 1 — Cao cấpja, ko, zh, de, ptllm (GPT-4o)Thị trường giá trị cao, ngữ pháp phức tạp
Cấp độ 2 — Tiêu chuẩnit, nl, pl, sv, da, fi, no, cs, ro, hu, el, tr, id, ms, th, vi, uk, bggoogle-translateKhối lượng lớn, được Google hỗ trợ tốt
Cấp độ 3 — Có hướng dẫncrk, oj, mi, hawllm-coached + pluginsÍt tài nguyên, cần tuân thủ thuật ngữ

Bước 2: Cấu hình cho từng cặp ngôn ngữ​

i18n-rosetta.config.json
{
  "version": 3,
  "inputLocale": "en",
  "localesDir": "./locales",
  "defaultMethod": "google-translate",
  "model": "google/gemini-3.5-flash",
  "languages": {
    "ja": { "name": "Japanese", "register": "Polite/formal" },
    "ko": { "name": "Korean", "register": "Formal" },
    "zh": { "name": "Simplified Chinese", "register": "Neutral" },
    "de": { "name": "German", "register": "Formal (Sie)" },
    "pt": { "name": "Brazilian Portuguese", "register": "Informal" },
    "crk": { "name": "Plains Cree (SRO)", "register": "Neutral" }
  },
  "pairs": {
    "en:ja": { "method": "llm", "model": "openai/gpt-4o" },
    "en:ko": { "method": "llm", "model": "openai/gpt-4o" },
    "en:zh": { "method": "llm", "model": "openai/gpt-4o" },
    "en:de": { "method": "llm", "model": "openai/gpt-4o" },
    "en:pt": { "method": "llm", "model": "openai/gpt-4o" },
    "en:crk": { "methodPlugin": "crk-coached-v1" }
  }
}

Lưu ý: Các ngôn ngữ không được liệt kê trong pairs sẽ kế thừa defaultMethod: "google-translate". Bạn không cần phải liệt kê toàn bộ 30 ngôn ngữ.

thông tin

Hỗ trợ crk đang được phát triển — xem Hỗ trợ ngôn ngữ ít tài nguyên để biết trạng thái và hướng dẫn đóng góp.

Bước 3: Thiết lập API Keys​

Bạn sẽ cần cả hai API key cho cấu hình này:

export OPENROUTER_API_KEY="sk-or-v1-..."
export GOOGLE_TRANSLATE_API_KEY="AIza..."

Bước 4: Chạy thử (Dry Run) trước​

Luôn xem trước khi dịch 30 ngôn ngữ:

npx i18n-rosetta sync --dry

Hãy xem lại kết quả đầu ra. Nó sẽ hiển thị:

  • Cặp ngôn ngữ nào sử dụng phương pháp nào
  • Có bao nhiêu key mới/thay đổi cho mỗi ngôn ngữ
  • Ước tính số lượt gọi API cho mỗi cấp độ

Bước 5: Chạy đồng bộ (Sync)​

npx i18n-rosetta sync

Rosetta xử lý từng cặp ngôn ngữ một cách độc lập. Các cặp Cấp độ 2 sử dụng Google Translate sẽ rất nhanh. Các cặp LLM Cấp độ 1 sẽ chậm hơn nhưng chất lượng cao hơn. Các cặp có hướng dẫn Cấp độ 3 sử dụng dữ liệu hướng dẫn (coaching data) của plugin.

Cập nhật tăng dần (Incremental Updates)​

Sau lần đồng bộ đầu tiên, các lần chạy tiếp theo sẽ chỉ dịch các key bị thay đổi hoặc mới thêm:

# Only keys that changed since last sync
npx i18n-rosetta sync

Tệp khóa (lock file) (.i18n-rosetta.lock) theo dõi những gì đã được dịch, vì vậy bạn sẽ không bao giờ phải dịch lại các nội dung đã ổn định.

Bước 6: Kiểm tra chất lượng​

Kiểm tra trạng thái của tất cả các cặp ngôn ngữ:

npx i18n-rosetta status

Lệnh này xuất ra một bảng hiển thị phương pháp, model, cấp độ chất lượng của từng cặp ngôn ngữ và liệu có sẵn dữ liệu hướng dẫn hay điểm chuẩn (benchmark scores) hay không.

Bước 7: Tích hợp CI​

Thêm vào workflow GitHub Actions của bạn để các bản dịch luôn được cập nhật trên mỗi lượt push:

.github/workflows/i18n-sync.yml
name: Sync Translations
on:
  push:
    paths:
      - 'locales/en/**'

jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - run: npm ci

      - name: Sync translations
        run: npx i18n-rosetta sync
        env:
          OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
          GOOGLE_TRANSLATE_API_KEY: ${{ secrets.GOOGLE_TRANSLATE_API_KEY }}

      - name: Commit updated translations
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add locales/
          git diff --staged --quiet || git commit -m "chore(i18n): sync translations"
          git push

Ước tính chi phí​

Đối với một dự án có 500 source key trên 30 ngôn ngữ:

Cấp độNgôn ngữPhương phápChi phí ước tính
Cấp độ 1 (5 ngôn ngữ)ja, ko, zh, de, ptGPT-4o~$2.50/lần đồng bộ toàn bộ
Cấp độ 2 (18 ngôn ngữ)it, nl, pl, v.v.Google Translate~$0.90/lần đồng bộ toàn bộ
Cấp độ 3 (4 ngôn ngữ)crk, oj, mi, hawGPT-4o-mini có hướng dẫn~$0.40/lần đồng bộ toàn bộ
Tổng cộng30 ngôn ngữHỗn hợp~$3.80/lần đồng bộ toàn bộ

Các lần đồng bộ tăng dần (5–20 key thay đổi) chỉ tốn một phần nhỏ chi phí so với đồng bộ toàn bộ.

Xem thêm​