Các phương thức dịch thuật

Champollion hỗ trợ mười phương thức dịch thuật. Mỗi cặp ngôn ngữ có thể sử dụng một phương thức khác nhau — bạn không bị ràng buộc vào một cách tiếp cận duy nhất cho toàn bộ dự án của mình.

So sánh các phương thức

Các nhà cung cấp LLM

Tập trung vào chất lượng, nhận biết được Markdown, tương thích với tính năng huấn luyện (coaching). Tốt nhất cho các dự án có nhiều nội dung.

Phương thức	Khóa (Key)	Chức năng
`llm` (mặc định)	`OPENROUTER_API_KEY`	LLM qua OpenRouter — hơn 200 mô hình, tự động định tuyến
`llm-coached`	`OPENROUTER_API_KEY`	LLM + quy tắc ngữ pháp, từ điển, lưu ý về phong cách
`openai`	`OPENAI_API_KEY`	API OpenAI trực tiếp (gpt-4o, gpt-4o-mini)
`anthropic`	`ANTHROPIC_API_KEY`	API Anthropic trực tiếp (Claude Sonnet, Haiku, Opus)
`gemini`	`GEMINI_API_KEY`	API Google Gemini trực tiếp (Flash, Pro) — có gói miễn phí

Dịch máy truyền thống (Traditional MT)

Tập trung vào tốc độ và chi phí. Tốt nhất cho các cặp khóa-giá trị (key-value) số lượng lớn.

Phương thức	Khóa (Key)	Chức năng
`google-translate`	`GOOGLE_TRANSLATE_API_KEY`	Google Cloud Translation API v2 (hơn 130 ngôn ngữ)
`deepl`	`DEEPL_API_KEY`	API DeepL hỗ trợ bảng thuật ngữ (hơn 30 ngôn ngữ)
`microsoft-translator`	`MICROSOFT_TRANSLATOR_API_KEY`	Azure Cognitive Services Translator (hơn 100 ngôn ngữ)
`libretranslate`	(tự lưu trữ)	LibreTranslate tự lưu trữ (AGPL, miễn phí)

Cơ sở hạ tầng

Phương thức	Khóa (Key)	Chức năng
`api`	(theo từng nhà cung cấp)	HTTP client tinh gọn cho bất kỳ endpoint dịch thuật REST nào

Sơ đồ quyết định

`llm` — Dịch thuật bằng LLM (Mặc định)

Dịch thông qua bất kỳ LLM nào trên OpenRouter. Đây là phương thức mặc định và linh hoạt nhất.

Cách hoạt động:

Gom nhóm các khóa (mặc định 80 khóa/nhóm) kèm theo hướng dẫn về văn phong và ngữ cảnh
Gửi đến OpenRouter dưới dạng một prompt có cấu trúc
Phân tích cú pháp phản hồi JSON
Xác thực từng bản dịch thông qua cổng chất lượng
Ghi lại các bản dịch đạt yêu cầu, thử lại hoặc từ chối các bản dịch không đạt

Khi nào nên sử dụng: Hầu hết các dự án. Đặc biệt là các trang web có nhiều nội dung bằng Markdown, nơi các khối mã (code block) và shortcode cần được bảo vệ.

Cấu hình:

{
  "defaultMethod": "llm",
  "model": "google/gemini-3.5-flash"
}

`llm-coached` — Dịch thuật LLM có huấn luyện (Coached LLM)

Tương tự như llm, nhưng có thêm các quy tắc ngữ pháp, từ điển thuật ngữ và lưu ý về phong cách được đưa vào mỗi prompt.

Cách hoạt động:

Tải dữ liệu huấn luyện từ thư mục .champollion/coaching/<locale>.json hoặc thư mục coaching/ của plugin
Đưa các quy tắc ngữ pháp, thuật ngữ từ điển và lưu ý phong cách vào system prompt
Các thuật ngữ trong từ điển khớp với các khóa nguồn sẽ được đưa vào dưới dạng thuật ngữ bắt buộc
Quá trình dịch thuật diễn ra tương tự như với llm, trong đó dữ liệu huấn luyện giúp tăng độ chính xác

Khi nào nên sử dụng: Các ngôn ngữ ít tài nguyên (low-resource), thuật ngữ chuyên ngành (pháp lý, y tế), văn phong trang trọng, hoặc bất kỳ trường hợp nào mà kết quả đầu ra của LLM thông thường không đủ chính xác.

Định dạng dữ liệu huấn luyện:

.champollion/coaching/fr.json
{
  "grammar_rules": [
    "French adjectives agree in gender and number with the noun they modify",
    "Use 'vous' for formal contexts, 'tu' for informal"
  ],
  "dictionary": {
    "dashboard": "tableau de bord",
    "deployment": "déploiement",
    "settings": "paramètres"
  },
  "style_notes": "Prefer active voice. Avoid anglicisms where a native French term exists."
}

Xem thêm: Hướng dẫn về ngôn ngữ ít tài nguyên

`openai` — API OpenAI trực tiếp

Dịch trực tiếp qua OpenAI Chat Completions API. Không qua trung gian OpenRouter — khóa của bạn, tài khoản của bạn, bảng điều khiển mức độ sử dụng của bạn.

Mô hình: gpt-4o (mặc định), gpt-4o-mini

Tính năng:

✅ Nhận biết được Markdown (dịch thuật nội dung)
✅ Hỗ trợ huấn luyện (quy tắc ngữ pháp, ghi đè từ điển, lưu ý phong cách)
✅ Chế độ JSON cho đầu ra dạng khóa-giá trị có cấu trúc
✅ Cơ chế exponential backoff (giảm tốc lũy thừa) khi thử lại

Cấu hình:

{
  "pairs": {
    "en:fr": { "method": "openai", "model": "gpt-4o-mini" }
  }
}

export OPENAI_API_KEY=sk-proj-...

Lấy khóa của bạn tại platform.openai.com/api-keys.

`anthropic` — API Anthropic trực tiếp

Dịch trực tiếp qua Anthropic Messages API. Sử dụng tham số system cho dữ liệu huấn luyện, cho phép kích hoạt tính năng lưu tạm prompt (prompt caching) của Anthropic.

Mô hình: claude-sonnet-4-6 (mặc định), claude-haiku-4-5, claude-opus-4-7

Tính năng:

✅ Nhận biết được Markdown (dịch thuật nội dung)
✅ Hỗ trợ huấn luyện (quy tắc ngữ pháp, ghi đè từ điển, lưu ý phong cách)
✅ Lưu tạm system prompt (phân bổ chi phí huấn luyện qua các nhóm)
✅ Cơ chế exponential backoff khi thử lại

Cấu hình:

{
  "pairs": {
    "en:ja": { "method": "anthropic", "model": "claude-haiku-4-5" }
  }
}

export ANTHROPIC_API_KEY=sk-ant-...

Lấy khóa của bạn tại console.anthropic.com.

`gemini` — API Google Gemini trực tiếp

Dịch trực tiếp qua Google Gemini generateContent API. Có sẵn gói miễn phí — điểm khởi đầu không tốn chi phí tốt nhất.

Mô hình: gemini-2.5-flash (mặc định), gemini-2.5-pro

Tính năng:

✅ Nhận biết được Markdown (dịch thuật nội dung)
✅ Hỗ trợ huấn luyện (quy tắc ngữ pháp, ghi đè từ điển, lưu ý phong cách)
✅ Chế độ phản hồi JSON qua responseMimeType
✅ Gói miễn phí (hạn mức hàng ngày hào phóng)
✅ Cơ chế exponential backoff khi thử lại

Cấu hình:

{
  "pairs": {
    "en:ko": { "method": "gemini", "model": "gemini-2.5-pro" }
  }
}

export GEMINI_API_KEY=AI...

Lấy khóa của bạn tại aistudio.google.com/apikey.

Xác thực mô hình

Các nhà cung cấp LLM trực tiếp (openai, anthropic, gemini) sẽ xác thực chuỗi mô hình của bạn trong lần sử dụng đầu tiên. Việc này giúp phát hiện ba nhóm lỗi sau:

Sai định dạng phương thức — Sử dụng đường dẫn mô hình theo kiểu OpenRouter với một nhà cung cấp trực tiếp:

[WARN] OpenAI: model "google/gemini-3.5-flash" looks like an OpenRouter path.
       Direct providers use bare model names (e.g., "gpt-4o").
       To use OpenRouter models, set method to 'llm' instead.

Sai nhà cung cấp — Sử dụng mô hình từ một nhà cung cấp hoàn toàn khác:

[WARN] Gemini: model "claude-sonnet-4-6" is an Anthropic model.
       This provider (gemini) cannot serve Anthropic models.
       Use --method anthropic or set "method": "anthropic" in config.

Mô hình đã lỗi thời hoặc viết sai chính tả — Trong cuộc gọi API đầu tiên, Champollion sẽ lấy danh sách mô hình thực tế của nhà cung cấp và đối chiếu mô hình của bạn với danh sách đó:

[WARN] Gemini: model "gemini-1.5-flash" not found in available models.
       Similar models: gemini-2.0-flash, gemini-2.5-flash, gemini-2.5-pro
       The API call will proceed — the provider will give the final verdict.

:::note Đây là các cảnh báo, không phải lỗi Việc xác thực mô hình chỉ ghi lại các cảnh báo chứ không chặn cuộc gọi API. API của nhà cung cấp mới là nơi đưa ra quyết định cuối cùng — một tên mô hình trong tương lai có thể khớp với một mẫu khác, và chúng tôi không muốn chặn dựa trên các phương pháp phỏng đoán (heuristics). :::

`google-translate` — Google Cloud Translation API

Tích hợp trực tiếp với Google Cloud Translation API v2. Sử dụng REST API — không cần SDK, không cần tài khoản dịch vụ (service account). Chỉ cần API key.

Khi nào nên sử dụng: Các cặp chuỗi khóa-giá trị số lượng lớn, nơi tốc độ và chi phí quan trọng hơn sắc thái ngôn từ. Hỗ trợ sẵn hơn 130 ngôn ngữ.

Hạn chế:

⚠️ Không nhận biết được Markdown. Sẽ làm hỏng các khối mã, shortcode và các biến nội suy (interpolation variables).
Không kiểm soát được văn phong/tông giọng
Không hỗ trợ huấn luyện hoặc áp đặt thuật ngữ

npx champollion sync --method google-translate

:::tip Tự động phát hiện Nếu chỉ có GOOGLE_TRANSLATE_API_KEY được thiết lập (không có khóa OpenRouter), Champollion sẽ tự động chuyển sang Google Translate. Không cần thay đổi cấu hình. :::

`deepl` — DeepL API

Tích hợp trực tiếp với API dịch thuật DeepL. Hỗ trợ bảng thuật ngữ (glossary) để đảm bảo tính nhất quán của thuật ngữ.

Khi nào nên sử dụng: Các ngôn ngữ châu Âu mà DeepL vượt trội (tiếng Đức, tiếng Pháp, tiếng Tây Ban Nha, tiếng Hà Lan, tiếng Ba Lan, v.v.). Việc hỗ trợ bảng thuật ngữ giúp áp đặt các thuật ngữ nhất quán mà không cần dữ liệu huấn luyện.

Tính năng:

✅ Tự động phát hiện endpoint free/pro (hậu tố :fx trên các khóa miễn phí)
✅ Tạo và quản lý bảng thuật ngữ
✅ Kiểm soát mức độ trang trọng (formality)
⚠️ Không nhận biết được Markdown — chỉ dành cho các cặp khóa-giá trị

Cấu hình:

{
  "pairs": {
    "en:de": { "method": "deepl" }
  }
}

export DEEPL_API_KEY=your-key-here

Lấy khóa của bạn tại deepl.com/pro-api.

`microsoft-translator` — Azure Cognitive Services

Tích hợp trực tiếp với Microsoft Translator Text API v3.

Khi nào nên sử dụng: Môi trường doanh nghiệp đã có sẵn cơ sở hạ tầng Azure. Hỗ trợ hơn 100 ngôn ngữ, bao gồm nhiều ngôn ngữ mà Google Translate không hỗ trợ.

Tính năng:

✅ Lên đến 100 phân đoạn (segment) mỗi yêu cầu (thông lượng cao)
✅ Tham số khu vực (region) tùy chọn để tối ưu hóa độ trễ
⚠️ Không nhận biết được Markdown — chỉ dành cho các cặp khóa-giá trị
⚠️ Không dịch thuật nội dung — chỉ dành cho các cặp khóa-giá trị

Cấu hình:

{
  "pairs": {
    "en:ar": { "method": "microsoft-translator" }
  }
}

export MICROSOFT_TRANSLATOR_API_KEY=your-key
export MICROSOFT_TRANSLATOR_REGION=global  # optional

Lấy khóa của bạn từ Azure Portal → Cognitive Services → Translator.

`libretranslate` — Dịch thuật tự lưu trữ (Self-Hosted)

Dịch thuật mã nguồn mở tự lưu trữ bằng LibreTranslate. Chạy cục bộ hoặc trên cơ sở hạ tầng của riêng bạn — không tốn chi phí API, chủ quyền dữ liệu hoàn toàn.

Khi nào nên sử dụng: Các dự án yêu cầu dịch thuật ngoại tuyến, tuân thủ quyền riêng tư dữ liệu (GDPR) hoặc vận hành không tốn chi phí. Đặc biệt hữu ích cho các pipeline CI không nên phụ thuộc vào các API bên ngoài.

Tính năng:

✅ Tự lưu trữ — không gọi API bên ngoài
✅ Miễn phí và mã nguồn mở (AGPL-3.0)
✅ Có sẵn triển khai bằng Docker
⚠️ Không nhận biết được Markdown — chỉ dành cho các cặp khóa-giá trị
⚠️ Không dịch thuật nội dung — chỉ dành cho các cặp khóa-giá trị
⚠️ Chất lượng khác nhau tùy thuộc vào từng cặp ngôn ngữ

Cài đặt:

# Run LibreTranslate locally with Docker
docker run -d -p 5000:5000 libretranslate/libretranslate

# Configure (optional — defaults to localhost:5000)
export LIBRETRANSLATE_API_URL=http://localhost:5000/translate

{
  "pairs": {
    "en:es": { "method": "libretranslate" }
  }
}

`api` — API dịch thuật từ xa (Remote Translation API)

Một HTTP client tinh gọn dành cho các endpoint dịch thuật do cộng đồng lưu trữ hoặc được bảo vệ quyền sở hữu trí tuệ (IP). Champollion gửi các khóa đi và nhận lại các bản dịch — nó không chứa bất kỳ logic dịch thuật nào.

Khi nào nên sử dụng: Khi các phương thức dịch thuật được lưu trữ ở phía máy chủ (ví dụ: dữ liệu huấn luyện độc quyền, các mô hình đã được tinh chỉnh, các pipeline FST không thể phân phối).

{
  "pairs": {
    "en:crk": {
      "method": "api",
      "endpoint": "https://api.example.com/v1/translate",
      "apiKey": "your-key"
    }
  }
}

:::note Dịch thuật cộng đồng tương thích với OCAP Phương thức api là cầu nối dẫn đến dịch thuật do cộng đồng lưu trữ tương thích với OCAP. Các cộng đồng ngôn ngữ bản địa và ngôn ngữ thiểu số có thể tự lưu trữ các endpoint dịch thuật của riêng họ — giữ cho dữ liệu huấn luyện, các mô hình tinh chỉnh và tài sản trí tuệ ngôn ngữ nằm dưới sự kiểm soát của cộng đồng — trong khi Champollion kết nối với chúng như một client tinh gọn.

Xem Hỗ trợ ngôn ngữ ít tài nguyên để biết toàn bộ hướng dẫn lưu trữ cộng đồng, và Cung cấp phương thức qua API để biết các yêu cầu về endpoint. :::

Cấu hình theo từng cặp

Sức mạnh thực sự nằm ở việc kết hợp các phương thức cho từng cặp ngôn ngữ:

champollion.config.json
{
  "version": 3,
  "pairs": {
    "en:fr": { "method": "deepl" },
    "en:ja": { "method": "openai", "model": "gpt-4o" },
    "en:ko": { "method": "gemini" },
    "en:ar": { "method": "microsoft-translator" },
    "en:crk": { "methodPlugin": "crk-coached-v1" }
  }
}

Cấu hình này dịch tiếng Pháp qua DeepL (hỗ trợ bảng thuật ngữ), tiếng Nhật qua OpenAI (chất lượng), tiếng Hàn qua Gemini (gói miễn phí), tiếng Ả Rập qua Microsoft Translator (độ phủ), và tiếng Plains Cree qua một plugin có huấn luyện (chuyên biệt).

Plugin

Plugin là các công thức dịch thuật được đóng gói sẵn cho các cặp ngôn ngữ cụ thể. Chúng là các tệp manifest JSON — không phải mã nguồn — hướng dẫn Champollion sử dụng phương thức nào, với các thiết lập gì và chất lượng đã được đo kiểm (benchmark) ra sao.

:::tip Từ môi trường đánh giá lên môi trường production chỉ với một lệnh Các plugin được phát triển và chứng minh hiệu quả trong môi trường đánh giá (eval harness) có thể được cài đặt trực tiếp — phương thức bạn xác thực ở đó sẽ được triển khai tại đây chỉ với một lệnh plugin install duy nhất. Xem Đánh giá dịch máy (MT Evaluation) để biết toàn bộ quy trình đánh giá. :::

champollion plugin install ./french-formal-v1/
champollion plugin list
champollion plugin remove french-formal-v1

Xem Đặc tả Plugin để biết định dạng manifest đầy đủ.

Chuyển đổi nhà cung cấp

Bạn muốn chuyển đổi giữa các phương thức? Định dạng mô hình và biến môi trường (env var) sẽ thay đổi — dưới đây là sơ đồ chuyển đổi:

OpenRouter → Nhà cung cấp trực tiếp

champollion.config.json
 {
   "pairs": {
     "en:fr": {
-      "method": "llm",
-      "model": "openai/gpt-4o"
+      "method": "openai",
+      "model": "gpt-4o"
     }
   }
 }

Environment variables
- export OPENROUTER_API_KEY=sk-or-v1-...
+ export OPENAI_API_KEY=sk-proj-...

Các điểm khác biệt chính:

OpenRouter sử dụng định dạng provider/model (ví dụ: openai/gpt-4o). Các nhà cung cấp trực tiếp sử dụng tên mô hình thuần túy (ví dụ: gpt-4o).
Mỗi nhà cung cấp trực tiếp có biến môi trường riêng (OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY).
Nếu bạn sử dụng sai định dạng mô hình, Champollion sẽ cảnh báo bạn — xem Xác thực mô hình.

Nhà cung cấp trực tiếp → OpenRouter

champollion.config.json
 {
   "pairs": {
     "en:ja": {
-      "method": "anthropic",
-      "model": "claude-sonnet-4-6"
+      "method": "llm",
+      "model": "anthropic/claude-sonnet-4-6"
     }
   }
 }

:::tip Khi nào nên dùng OpenRouter so với trực tiếp Sử dụng OpenRouter khi bạn muốn chuyển đổi giữa các mô hình mà không cần thay đổi các biến môi trường, hoặc khi bạn muốn truy cập hơn 200 mô hình chỉ với một khóa duy nhất. Sử dụng nhà cung cấp trực tiếp khi bạn muốn thanh toán đơn giản hơn, độ trễ thấp hơn (không qua trung gian) hoặc muốn tiếp cận các tính năng đặc thù của nhà cung cấp như tính năng lưu tạm prompt của Anthropic. :::

So sánh chi phí

Chi phí ước tính trên 1.000 khóa được dịch (giả định khoảng 10 token mỗi khóa, 80 khóa mỗi nhóm):

Phương thức	Chi phí / 1K khóa	Tốc độ	Chất lượng	Phù hợp nhất cho
`gemini` (Flash)	Miễn phí (trong hạn mức)	Nhanh	Tốt	Bắt đầu, dự án cá nhân
`google-translate`	~0,02 USD	Nhanh nhất	Đủ dùng	Số lượng lớn, ngôn ngữ châu Âu
`deepl`	~0,02 USD	Nhanh	Tốt	Ngôn ngữ châu Âu, thuật ngữ
`microsoft-translator`	~0,01 USD	Nhanh	Đủ dùng	Hệ thống Azure, độ phủ ngôn ngữ rộng
`libretranslate`	Miễn phí (tự lưu trữ)	Thay đổi	Khá	Môi trường cô lập (air-gapped), GDPR, pipeline CI
`gemini` (Pro)	~0,07 USD	Trung bình	Rất tốt	Nhạy cảm với chất lượng, hạn mức miễn phí
`openai` (GPT-4o-mini)	~0,01 USD	Nhanh	Tốt	LLM tiết kiệm chi phí
`openai` (GPT-4o)	~0,10 USD	Trung bình	Rất tốt	Nhạy cảm với chất lượng
`anthropic` (Haiku)	~0,01 USD	Nhanh	Tốt	LLM tiết kiệm chi phí
`anthropic` (Sonnet)	~0,10 USD	Trung bình	Rất tốt	Nhạy cảm với chất lượng
`anthropic` (Opus)	~0,50 USD	Chậm	Xuất sắc	Chất lượng tối đa
`llm` (OpenRouter)	Thay đổi theo mô hình	Thay đổi	Thay đổi	So sánh mô hình, thử nghiệm

:::note Đây là các ước tính Chi phí thực tế phụ thuộc vào độ dài văn bản nguồn, kích thước nhóm (batch size) và thay đổi giá của nhà cung cấp. Hãy kiểm tra trang giá hiện tại của từng nhà cung cấp để biết mức phí chính xác. :::

Xem thêm

Ngôn ngữ được hỗ trợ
Dữ liệu huấn luyện
Hỗ trợ ngôn ngữ ít tài nguyên
Đặc tả Plugin
Cung cấp phương thức qua API
Cổng chất lượng
Kiến trúc
Khắc phục sự cố — lỗi mô hình, sự cố API

So sánh các phương thức​

Các nhà cung cấp LLM​

Dịch máy truyền thống (Traditional MT)​

Cơ sở hạ tầng​

Sơ đồ quyết định​

llm — Dịch thuật bằng LLM (Mặc định)​

llm-coached — Dịch thuật LLM có huấn luyện (Coached LLM)​

openai — API OpenAI trực tiếp​

anthropic — API Anthropic trực tiếp​

gemini — API Google Gemini trực tiếp​

Xác thực mô hình​

google-translate — Google Cloud Translation API​

deepl — DeepL API​

microsoft-translator — Azure Cognitive Services​

libretranslate — Dịch thuật tự lưu trữ (Self-Hosted)​

api — API dịch thuật từ xa (Remote Translation API)​

Cấu hình theo từng cặp​

Plugin​

Chuyển đổi nhà cung cấp​

OpenRouter → Nhà cung cấp trực tiếp​

Nhà cung cấp trực tiếp → OpenRouter​

So sánh chi phí​

Xem thêm​

So sánh các phương thức

Các nhà cung cấp LLM

Dịch máy truyền thống (Traditional MT)

Cơ sở hạ tầng

Sơ đồ quyết định

`llm` — Dịch thuật bằng LLM (Mặc định)

`llm-coached` — Dịch thuật LLM có huấn luyện (Coached LLM)

`openai` — API OpenAI trực tiếp

`anthropic` — API Anthropic trực tiếp

`gemini` — API Google Gemini trực tiếp

Xác thực mô hình

`google-translate` — Google Cloud Translation API

`deepl` — DeepL API

`microsoft-translator` — Azure Cognitive Services

`libretranslate` — Dịch thuật tự lưu trữ (Self-Hosted)

`api` — API dịch thuật từ xa (Remote Translation API)

Cấu hình theo từng cặp

Plugin

Chuyển đổi nhà cung cấp

OpenRouter → Nhà cung cấp trực tiếp

Nhà cung cấp trực tiếp → OpenRouter

So sánh chi phí

Xem thêm