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ữ (locale) lên quy mô toàn cầu. Hướng dẫn này sẽ đi qua các bước lựa chọn phương thức dịch, tối ưu hóa chi phí và tích hợp CI cho một hệ thống triển khai đa ngôn ngữ thực tế.

Kịch bản: Bạn có một ứng dụng SaaS với en, fr, es. Bạn cần thêm 27 ngôn ngữ khác chia theo ba cấp độ yêu cầu chất lượng.

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

Không phải tất cả 30 ngôn ngữ đều cần cách tiếp cận giống nhau. Hãy nhóm chúng lại theo chất lượng phương thức dịch hiện có:

Cấp độNgôn ngữPhương thứcLý do
Cấp độ 1 — Cao cấpja, ko, zh, de, ptllm (GPT-4o)Thị trường giá trị cao, ngữ pháp sắc thái 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ó huấn luyệncrk, oj, mi, hawllm-coached + pluginsTài nguyên ít, yêu cầu áp dụng thuật ngữ nghiêm ngặt

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

champollion.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ê cả 30 ngôn ngữ.

thông tin

Hỗ trợ cho 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 Key​

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ử trước (Dry Run)​

Luôn xem trước kết quả trước khi dịch 30 ngôn ngữ:

npx champollion sync --dry

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 thức nào
  • Có bao nhiêu khóa (key) mới/thay đổi trên mỗi ngôn ngữ (locale)
  • Ước tính số lượng gọi API cho mỗi cấp độ

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

npx champollion sync

Champollion 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ẽ dịch rất nhanh. Các cặp LLM Cấp độ 1 sẽ chậm hơn nhưng có chất lượng cao hơn. Các cặp có huấn luyện Cấp độ 3 sẽ sử dụng dữ liệu huấn luyện (coaching data) của plugin.

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

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

# Only keys that changed since last sync
npx champollion sync

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

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

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

npx champollion status

Lệnh này sẽ xuất ra một bảng hiển thị phương thức, mô hình, cấp độ chất lượng của từng cặp, và liệu dữ liệu huấn luyện hoặc điểm số đánh giá (benchmark) có sẵn hay không.

Kết quả đầu ra có tuân thủ văn phong (register) của bạn không?​

Trong Bước 2, bạn đã khai báo một văn phong (register) cho mỗi ngôn ngữ — "Polite/formal" cho tiếng Nhật, "Formal (Sie)" cho tiếng Đức. (Bạn mới nghe thuật ngữ này lần đầu? Trang thuật ngữ giải thích nó bằng ngôn ngữ bình dân dễ hiểu.) Những hướng dẫn đó sẽ được đưa vào prompt dịch thuật, nhưng prompt chỉ là một yêu cầu chứ không phải là một sự đảm bảo tuyệt đối.

Bộ công cụ MT Eval Arena harness — cùng một công cụ vận hành bảng xếp hạng công khai — có thể đo lường mức độ tuân thủ văn phong và phong cách trên một mẫu bản dịch của bạn. Các chỉ số phong cách viết của nó sẽ kiểm tra từng kết quả đầu ra so với văn phong mong đợi (các dấu hiệu trang trọng/thân mật, đại từ nhân xưng, từ viết tắt, sự thay đổi độ dài câu) và báo cáo một style_consistency_rate trong suốt quá trình chạy. Bạn cũng có thể hướng nó đến một hồ sơ giọng điệu thương hiệu tùy chỉnh với --style-profile.

# install the harness, then run your sample corpus through it
curl -fsSL champollion.dev/harness | bash
mt-eval run --corpus my-sample.json --style-profile brand-voice.json

Hai lưu ý trung thực: các chỉ số này chỉ mang tính chất tham khảo (chúng không bao giờ được tính vào điểm tổng hợp của bảng xếp hạng) và việc phát hiện mức độ trang trọng dựa trên các dấu hiệu nhận biết — một công cụ phát hiện sự lệch hướng chứ không phải là đánh giá của con người. Chi tiết và định nghĩa chỉ số: Chỉ số phong cách viết và văn phong.

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

Thêm vào quy trình làm việc (workflow) GitHub Actions của bạn để các bản dịch luôn được cập nhật sau mỗi lần 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 champollion 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 khóa nguồn trên 30 ngôn ngữ:

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

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

Xem thêm​