Hướng dẫn dành cho Agent: Sử dụng champollion
champollion là một công cụ CLI giúp dịch các tệp ngôn ngữ (locale) của ứng dụng chỉ bằng một câu lệnh. Hướng dẫn này dành cho các AI agent (hoặc lập trình viên làm việc với AI agent) muốn đi từ con số không đến các tệp ngôn ngữ đã được dịch một cách nhanh chóng.
:::tip Đã quen thuộc? Nếu bạn chỉ cần các câu lệnh, hãy chuyển ngay đến Tài liệu tham khảo CLI. Nếu bạn muốn xây dựng và đánh giá hiệu năng (benchmark) một phương thức dịch thuật, hãy xem Hướng dẫn dành cho Arena Agent. :::
Thiết lập môi trường
# No global install needed — npx runs it directly
npx champollion sync
Yêu cầu:
- Node.js 18+
- Một API key cho nhà cung cấp dịch vụ dịch thuật của bạn
Thiết lập API key — champollion cần ít nhất một key tùy thuộc vào phương thức bạn sử dụng:
# Option 1: export (session only)
export OPENROUTER_API_KEY="sk-or-..." # for llm / llm-coached methods
export GOOGLE_TRANSLATE_API_KEY="AIza..." # for google-translate method
# Option 2: .env file in your project root (persistent, gitignored)
echo 'OPENROUTER_API_KEY=sk-or-...' > .env
Champollion tự động đọc .env. Nhận OpenRouter key tại openrouter.ai/keys.
Đồng bộ lần đầu
Champollion tự động phát hiện các tệp ngôn ngữ của bạn, định dạng của chúng (JSON, TOML, YAML, PO) và các ngôn ngữ đích của bạn:
npx champollion sync
Điều gì xảy ra:
- Tải
champollion.config.json(hoặc tự động phát hiện các thiết lập) - Quét tệp ngôn ngữ nguồn của bạn, làm phẳng (flatten) các key lồng nhau
- So sánh với
.champollion.lock(mã băm SHA-256 của các giá trị đã dịch trước đó) - Kiểm tra
.champollion/tm.jsonđể tìm các bản dịch đã lưu trong bộ nhớ đệm (Translation Memory) - Chỉ dịch các key bị thay đổi, bị thiếu hoặc đã cũ thông qua phương thức đã cấu hình
- Chạy cổng kiểm soát chất lượng (quality gate - 5 bước kiểm tra) trên mỗi bản dịch
- Ghi các bản dịch đạt yêu cầu vào tệp ngôn ngữ đích
- Cập nhật lock file và bộ nhớ đệm TM
Trong một lần chạy lại thông thường sau khi thay đổi một key, bước 4 sẽ cung cấp 142 key từ bộ nhớ đệm và bước 5 chỉ dịch 1 key. Đây là lý do tại sao các lần đồng bộ tiếp theo diễn ra rất nhanh và tiết kiệm chi phí.
Cấu hình
Tạo champollion.config.json trong thư mục gốc của dự án:
{
"inputLocale": "en",
"pairs": {
"en-fr": { "method": "llm-coached" },
"en-ja": { "method": "google-translate" },
"en-crk": { "method": "api", "endpoint": "http://localhost:3000/translate" }
}
}
Các trường chính:
| Trường | Mục đích | Mặc định |
|---|---|---|
inputLocale | Ngôn ngữ nguồn | en |
pairs | Bản đồ ánh xạ nguồn→đích với cấu hình phương thức | (bắt buộc) |
localesDir | Nơi lưu trữ các tệp ngôn ngữ | (tự động phát hiện) |
model | Mô hình LLM cho các phương thức llm/llm-coached | google/gemini-2.5-flash |
batchSize | Số lượng key trên mỗi cuộc gọi API | 80 (LLM), 128 (Google) |
jsonConcurrency | Số lượng dịch song song các ngôn ngữ cho các key JSON | 200 |
contentConcurrency | Số lượng cuộc gọi API song song để dịch nội dung | 48 |
Tài liệu tham khảo đầy đủ: Cấu hình
Phương thức dịch thuật
| Phương thức | Khi nào nên dùng | Chi phí | API key cần thiết |
|---|---|---|---|
llm | Đa mục đích, tốt cho các ngôn ngữ có nhiều tài nguyên | Theo token (tùy thuộc vào mô hình) | OPENROUTER_API_KEY |
llm-coached | Khi bạn có các quy tắc ngữ pháp/từ điển cho ngôn ngữ đích | Theo token + ngữ cảnh huấn luyện (coaching context) | OPENROUTER_API_KEY |
google-translate | Các ngôn ngữ có nhiều tài nguyên mà Google Translate hoạt động tốt | $20/triệu ký tự | GOOGLE_TRANSLATE_API_KEY |
api | Pipeline tùy chỉnh được lưu trữ phía sau một HTTP endpoint | Do máy chủ quyết định | Không (endpoint tự xử lý xác thực) |
plugin | Phương thức đóng gói sẵn được cài đặt cục bộ | Thay đổi | Thay đổi |
Chi tiết: Phương thức dịch thuật
Dữ liệu huấn luyện (Coaching Data)
Đối với các cặp ngôn ngữ llm-coached, dữ liệu huấn luyện sẽ định hướng LLM bằng kiến thức ngôn ngữ rõ ràng. Tạo một tệp huấn luyện:
{
"grammar_rules": [
"Use formal register (vous) for all UI text",
"Adjectives agree in gender and number with the noun"
],
"dictionary": {
"dashboard": "tableau de bord",
"settings": "paramètres"
},
"style_notes": "Prefer active voice. Avoid anglicisms."
}
Tham chiếu nó trong cấu hình cặp ngôn ngữ của bạn:
"en-fr": { "method": "llm-coached", "coachingFile": "coaching/fr.json" }
Cổng kiểm soát chất lượng sẽ xác minh xem các thuật ngữ trong từ điển có thực sự xuất hiện trong kết quả đầu ra hay không — các trường hợp vi phạm sẽ được ghi nhận dưới dạng cảnh báo [TERM].
Chi tiết: Dữ liệu huấn luyện
Cổng kiểm soát chất lượng (Quality Gate)
Mỗi bản dịch đều phải trải qua năm bước kiểm tra tự động trước khi được ghi vào đĩa:
| Kiểm tra | Lỗi phát hiện | Ví dụ |
|---|---|---|
| Trống/rỗng | Mô hình không trả về kết quả | "" |
| Lặp lại nguồn | Mô hình trả về nguyên vẹn nội dung tiếng Anh đầu vào | "Welcome" cho tiếng Nhật |
| Vòng lặp ảo tưởng | Các cụm ba từ (trigram) bị lặp lại | "Qo' Qo' Qo' Qo'" |
| Phình to độ dài | Kết quả đầu ra dài gấp 4 lần trở lên so với nguồn | Nguồn 10 ký tự → Đầu ra 50 ký tự |
| Tuân thủ hệ chữ viết | Sai hệ chữ viết cho ngôn ngữ đó | Văn bản chữ Latin cho ngôn ngữ Ả Rập |
Các lỗi thất bại được ghi nhật ký với tiền tố [GATE]. Không có cơ chế dự phòng âm thầm (silent fallback) — nếu một bản dịch thất bại, nó sẽ được báo cáo chứ không âm thầm được chấp nhận.
Chi tiết: Cổng kiểm soát chất lượng
Bộ nhớ dịch thuật (Translation Memory)
Champollion lưu các bản dịch vào bộ nhớ đệm trong .champollion/tm.json, được định danh bằng văn bản nguồn + ngôn ngữ + phương thức. Trong các lần đồng bộ tiếp theo, các key không thay đổi sẽ được lấy từ bộ nhớ đệm — không cần gọi API, không tốn chi phí.
[TM] 142 key(s) served from cache
Translating 3 key(s) to French (llm)... [OK]
Để bỏ qua bộ nhớ đệm trong một lần chạy: npx champollion sync --no-tm
Chi tiết: Bộ nhớ dịch thuật
Các tệp được tạo ra
Champollion tạo ra một số tệp trong dự án của bạn. Hãy hiểu rõ chúng là gì để tránh vô tình xóa hoặc commit nhầm tệp:
| Tệp | Mục đích | Git? |
|---|---|---|
.champollion.lock | Mã băm SHA-256 của các giá trị nguồn đã dịch (để phát hiện thay đổi) | Có — hãy commit tệp này |
.champollion-content.lock | Tương tự, nhưng dành cho các tệp nội dung Markdown/MDX | Có — hãy commit tệp này |
.champollion/tm.json | Bộ nhớ đệm của Bộ nhớ dịch thuật (Translation Memory) | Có — hãy commit tệp này (giúp tiết kiệm chi phí API cho cả đội ngũ) |
.champollion/coaching/ | Thư mục dữ liệu huấn luyện | Có — đây là kiến thức ngôn ngữ của bạn |
champollion.config.json | Cấu hình dự án | Có — hãy commit tệp này |
Các mẫu lệnh phổ biến
Dịch một cặp ngôn ngữ:
npx champollion sync --pair en-fr
Dịch tất cả các cặp ngôn ngữ đã cấu hình:
npx champollion sync
Champollion dịch song song tất cả các ngôn ngữ. Với bộ nhớ đệm TM, chỉ các key bị thay đổi mới gọi đến API.
Chế độ nội dung (Markdown/MDX cho Docusaurus, Hugo, v.v.):
npx champollion sync --content
Dịch các tài liệu, bài viết blog và các tệp nội dung cùng với tệp JSON ngôn ngữ. Sử dụng tính năng xử lý song song (mặc định: 48 cuộc gọi API đồng thời). Điều chỉnh bằng --content-concurrency.
Chạy thử (xem trước mà không ghi tệp):
npx champollion sync --dry-run
Bắt buộc dịch lại các key cụ thể:
npx champollion sync --force-keys "hero.title,nav.about"
Bắt buộc dịch lại tất cả các tệp nội dung:
npx champollion sync --force-content
Kiểm tra trạng thái dịch thuật:
npx champollion status
Hiển thị mức độ bao phủ, các mức chất lượng và thông tin plugin cho từng cặp ngôn ngữ.
Kiểm tra các giá trị dự phòng chưa được dịch:
npx champollion audit
Liệt kê tất cả các giá trị dự phòng [EN] cần được dịch.
Khắc phục sự cố
| Sự cố | Cách khắc phục |
|---|---|
OPENROUTER_API_KEY not set | Export key đó hoặc thêm nó vào .env trong thư mục gốc của dự án |
No locale files found | Thiết lập localesDir trong cấu hình, hoặc đảm bảo các tệp ngôn ngữ của bạn khớp với cách đặt tên chuẩn (en.json, fr.json) |
[GATE] Script compliance failed | Ngôn ngữ đích của bạn nhận được văn bản chữ Latin thay vì hệ chữ viết mong muốn — hãy thử một mô hình khác hoặc thêm dữ liệu huấn luyện |
[GATE] Source echo | Mô hình trả về tiếng Anh không thay đổi — dữ liệu huấn luyện hoặc một mô hình khác thường sẽ khắc phục được lỗi này |
| Tất cả bản dịch đều được lấy từ bộ nhớ đệm | Chạy với --no-tm để bỏ qua bộ nhớ đệm, hoặc --force-keys cho các key cụ thể |
| Xung đột lock file | .champollion.lock sử dụng mã băm SHA-256 — việc giải quyết xung đột khi merge bằng cách giữ lại một trong hai phiên bản là an toàn, sau đó hãy chạy lại lệnh đồng bộ |
Bước tiếp theo
- Bắt đầu nhanh — hướng dẫn từng bước đầy đủ để bắt đầu
- Tài liệu tham khảo CLI — mọi câu lệnh và flag
- Cách thức hoạt động — giải thích về pipeline đồng bộ
- The Eval Harness Bridge — cách champollion kết nối với Arena
- Bạn muốn xây dựng phương thức dịch thuật của riêng mình? Hãy xem Hướng dẫn dành cho Arena Agent — xây dựng một phương thức, chứng minh nó hoạt động hiệu quả và giành giải thưởng.