Cấu hình
Champollion hoạt động mà không cần cấu hình (zero-config) — công cụ này tự động phát hiện các tệp ngôn ngữ (locale), định dạng và ngôn ngữ đích từ dự án của bạn. Để kiểm soát nhiều hơn, hãy tạo champollion.config.json trong thư mục gốc của dự án, hoặc chạy:
npx champollion init
Tài liệu tham khảo cấu hình đầy đủ
{
"version": 3,
"inputLocale": "en",
"localesDir": "./locales",
"contentDir": null,
"translatableFields": null,
"format": "auto",
"model": "google/gemini-3.5-flash",
"temperature": 0.3,
"defaultMethod": "llm",
"batchSize": 80,
"coachingFile": null,
"promptContext": null,
"jsonConcurrency": 200,
"contentConcurrency": 48,
"fallbackPrefix": "[EN] ",
"apiKeyEnvVar": "OPENROUTER_API_KEY",
"baseUrl": "",
"pairs": {},
"languages": {},
"lint": {
"srcDir": null,
"ignore": ["node_modules", ".next", "dist"],
"minLength": 2
},
"seo": {
"urlPattern": "/:locale/:path",
"pages": null
},
"typegen": {
"output": null,
"autoGenerate": false
}
}
:::note typegen chưa được triển khai
Khối cấu hình typegen được trình tải cấu hình nhận diện và bảo toàn, nhưng tính năng tạo kiểu TypeScript (type generation) vẫn chưa được triển khai. Đây là phần giữ chỗ cho một tính năng đã được lên kế hoạch. Việc thiết lập các giá trị này sẽ không có tác dụng.
:::
Các trường
| Trường | Kiểu dữ liệu | Mặc định | Mô tả |
|---|---|---|---|
version | number | 3 | Phiên bản schema cấu hình. Luôn là 3. |
inputLocale | string | "en" | Mã ngôn ngữ nguồn (BCP 47). |
localesDir | string | "./locales" | Đường dẫn đến các tệp ngôn ngữ. Champollion sẽ quét thư mục này. |
contentDir | string | null | Thư mục nội dung Hugo. Cho phép dịch phần thân Markdown. |
translatableFields | string[] | null | Ghi đè các trường frontmatter có thể dịch mặc định để dịch nội dung. null sử dụng các giá trị mặc định tích hợp sẵn (title, description, summary). |
format | string | "auto" | Định dạng tệp: json, toml, yaml, hoặc auto (tự động phát hiện từ phần mở rộng). |
model | string | "google/gemini-3.5-flash" | Mô hình mặc định cho các phương thức LLM. Chấp nhận slug OpenRouter đầy đủ (provider/model) hoặc các bí danh ngắn từ shared/model-aliases.json (ví dụ: gemini-flash). Các nhà cung cấp trực tiếp sử dụng tên trần (ví dụ: gpt-4o). |
temperature | number | 0.3 | Nhiệt độ (temperature) của LLM (0.0–2.0). Thấp hơn = mang tính xác định cao hơn. |
defaultMethod | string | "llm" | Phương thức dịch mặc định: llm, llm-coached, google-translate, deepl, microsoft-translator, libretranslate, openai, anthropic, gemini, api. Bị ghi đè bởi cờ CLI --method. |
batchSize | number | 80 | Số lượng khóa trên mỗi loạt (batch) dịch. Cao hơn = ít cuộc gọi API hơn, nhưng prompt sẽ lớn hơn. |
coachingFile | string | null | Đường dẫn đến tệp prompt huấn luyện (coaching prompt) dạng văn bản tự do (tương đối so với thư mục gốc của dự án). Nội dung được đọc khi khởi động và được chèn vào system prompt dưới dạng một khối Coaching guidance:. |
promptContext | string | null | Chuỗi ngữ cảnh ứng dụng được chèn vào system prompt (ví dụ: "E-commerce product descriptions"). Giúp mô hình điều chỉnh bản dịch phù hợp với lĩnh vực của bạn. |
jsonConcurrency | number | 200 | Số lượng bản dịch ngôn ngữ song song tối đa để đồng bộ hóa khóa JSON. Bị ghi đè bởi cờ CLI --json-concurrency. |
contentConcurrency | number | 48 | Số lượng cuộc gọi API song song tối đa để dịch nội dung (Markdown/MDX). Bị ghi đè bởi cờ CLI --content-concurrency. |
fallbackPrefix | string | "[EN] " | Tiền tố đánh dấu được sử dụng bởi audit and verify để phát hiện các giá trị chưa dịch cũ từ các lần chạy trước. Champollion không ghi tiền tố này — nó chỉ đọc để phát hiện. |
apiKeyEnvVar | string | "OPENROUTER_API_KEY" | Tên biến môi trường cho API key. Ghi đè đối với các tên biến môi trường tùy chỉnh. |
baseUrl | string | "" | URL cơ sở để tạo các thành phần SEO (hreflang, sitemaps, JSON-LD). |
pairs | object | {} | Ghi đè phương thức, mô hình và chất lượng cho từng cặp ngôn ngữ. Xem Cấu hình cặp ngôn ngữ. |
languages | object | {} | Ghi đè cho từng ngôn ngữ. Xem Cấu hình ngôn ngữ. |
lint.srcDir | string | null | Thư mục nguồn để quét lint. null = tự động phát hiện từ framework. |
lint.ignore | string[] | ["node_modules", ...] | Các mẫu glob để loại trừ khỏi quá trình quét lint. |
lint.minLength | number | 2 | Độ dài chuỗi tối thiểu để gắn cờ là hardcoded (mã hóa cứng). |
seo.urlPattern | string | "/:locale/:path" | Mẫu định dạng URL để tạo thẻ hreflang. |
seo.pages | string[] | null | Danh sách trang rõ ràng cho SEO. null = tự động phát hiện từ các khóa ngôn ngữ. |
typegen.output | string | null | Đường dẫn đầu ra cho các kiểu TypeScript được tạo. null = đã tắt. |
typegen.autoGenerate | boolean | false | Tự động tạo lại các kiểu sau mỗi lần đồng bộ hóa. |
Cấu hình cặp ngôn ngữ
Mỗi cặp nguồn→đích có thể được cấu hình độc lập:
{
"pairs": {
"en:fr": {
"method": "google-translate",
"qualityTier": "high"
},
"en:ja": {
"method": "llm",
"model": "google/gemini-2.5-pro"
},
"en:crk": {
"methodPlugin": "crk-coached-v1"
}
}
}
Các trường của cặp ngôn ngữ
| Trường | Kiểu dữ liệu | Mô tả |
|---|---|---|
method | string | Phương thức dịch: llm, llm-coached, google-translate, deepl, microsoft-translator, libretranslate, openai, anthropic, gemini, api |
methodPlugin | string | Tên của một plugin đã cài đặt (từ .champollion/methods/) |
model | string | Ghi đè mô hình mặc định cho cặp này |
temperature | number | Ghi đè nhiệt độ mặc định cho cặp này |
batchSize | number | Ghi đè kích thước loạt mặc định cho cặp này |
register | string | Ghi đè văn phong/giọng điệu (khóa thiết lập sẵn hoặc văn bản tự do) |
endpoint | string | URL điểm cuối API từ xa. Bắt buộc khi method là api. |
coachingFile | string | Đường dẫn đến tệp prompt huấn luyện cho cặp này |
promptContext | string | Ngữ cảnh ứng dụng cho cặp này |
qualityTier | string | Phân cấp hiển thị: standard, high, research, verified |
Cấu hình ngôn ngữ
Ngôn ngữ chấp nhận ba định dạng:
Mảng các mã ngôn ngữ (đơn giản nhất)
{
"languages": ["fr", "de", "ja"]
}
Mỗi ngôn ngữ sẽ nhận văn phong mặc định từ bảng văn phong tích hợp sẵn. Các ngôn ngữ không có mặc định sẽ nhận "Professional register.".
Đối tượng với các chuỗi văn phong
Giá trị có thể là một khóa thiết lập sẵn (preset key) từ thẻ của ngôn ngữ, hoặc văn bản văn phong tùy chỉnh:
{
"languages": {
"fr": "casual-tu",
"ko": "formal-hapsyo",
"ja": "Custom: Polite Japanese for a gaming app."
}
}
Champollion sẽ kiểm tra xem chuỗi có khớp với khóa thiết lập sẵn trong thẻ ngôn ngữ hay không. Nếu khớp, prompt văn phong đầy đủ từ thẻ sẽ được sử dụng. Nếu không, chuỗi sẽ được sử dụng nguyên trạng. Xem Ngôn ngữ được hỗ trợ để biết các thiết lập sẵn có sẵn.
Đối tượng với cấu hình đầy đủ
{
"languages": {
"crk": {
"name": "Plains Cree",
"register": "SRO syllabics with grammatical precision.",
"model": "google/gemini-2.5-pro",
"batchSize": 5,
"maxRetries": 5,
"script": "cans"
}
}
}
Bạn có thể kết hợp cú pháp viết tắt và các đối tượng đầy đủ trong cùng một khối.
Các trường ngôn ngữ
| Trường | Kiểu dữ liệu | Mô tả |
|---|---|---|
register | string | Hướng dẫn về phong cách/giọng điệu. Có thể là một khóa thiết lập sẵn (ví dụ: casual-tu, formal-hapsyo) hoặc văn bản tùy chỉnh. Xem Thẻ ngôn ngữ. |
name | string | Tên ngôn ngữ dễ đọc (để hiển thị trạng thái) |
model | string | Ghi đè mô hình mặc định |
temperature | number | Ghi đè nhiệt độ mặc định |
batchSize | number | Ghi đè kích thước loạt mặc định |
coachingFile | string | Đường dẫn đến tệp prompt huấn luyện cho ngôn ngữ này |
promptContext | string | Ngữ cảnh ứng dụng cho ngôn ngữ này |
maxRetries | number | Số lần thử lại tối đa cho các loạt bị lỗi (mặc định: 3) |
script | string | Mã chữ viết ISO 15924. Kích hoạt xác thực chữ viết trong cổng kiểm định chất lượng (quality gate). |
:::info Chuỗi kế thừa Các thiết lập được giải quyết theo thứ tự sau (ưu tiên cái đầu tiên):
cấp độ cặp (pair-level) → cấp độ ngôn ngữ (language-level) → cấu hình toàn cục (global config) → mặc định (defaults)
Ví dụ: nếu pairs["en:fr"] thiết lập model, nó sẽ ghi đè cả giá trị model ở cấp độ ngôn ngữ và toàn cục.
:::
Nguồn không phải tiếng Anh
Nếu ngôn ngữ nguồn của bạn không phải là tiếng Anh:
# CLI flag (one-time)
npx champollion sync --source fr
{
"inputLocale": "fr"
}
Tệp Lock
Champollion tạo ra .champollion.lock để theo dõi mã băm SHA-256 của các giá trị nguồn đã dịch. Hãy commit tệp này để tất cả các nhà phát triển chia sẻ cùng một cơ sở dịch thuật.
Khi một giá trị nguồn thay đổi, mã băm sẽ không còn khớp nữa và champollion sẽ dịch lại khóa đó trong lần đồng bộ tiếp theo.
.champollionignore
Tạo .champollionignore trong thư mục gốc của dự án để loại trừ các tệp khỏi quá trình quét lint. Sử dụng các mẫu glob, như .gitignore:
src/components/legacy/**
src/utils/constants.js
**/*.test.js
Thư mục .champollion/
Champollion tạo một thư mục .champollion/ trong thư mục gốc của dự án cho trạng thái nội bộ. Nhìn chung, bạn nên thêm thư mục này vào .gitignore — đây là tối ưu hóa cục bộ, không phải mã nguồn dự án:
.champollion/
| Tệp | Mục đích | Commit? |
|---|---|---|
tm.json | Bộ nhớ đệm Translation Memory — lưu trữ các bản dịch trước đó được định danh bằng văn bản nguồn + ngôn ngữ + phương thức | Không (bộ nhớ đệm cục bộ) |
xliff/*.xliff | Các tệp xuất XLIFF để biên dịch viên chuyên nghiệp xem xét | Không (tạm thời) |
methods/ | Manifest của các plugin phương thức đã cài đặt | Có (cấu hình chia sẻ) |
backups/ | Bản sao lưu trước khi bọc (được tạo bởi wrap --undo) | Không (mạng lưới an toàn) |
Xem Translation Memory để biết chi tiết về tm.json và cách nó tiết kiệm chi phí API.
API lập trình
Đối với các tập lệnh build và tích hợp tùy chỉnh, hãy import trực tiếp từ package:
import { GeminiMethod, runSync, resolveConfig } from 'champollion';
// Use a method class directly
const gemini = new GeminiMethod();
const result = await gemini.translate(
['greeting', 'farewell'],
{ greeting: 'Hello', farewell: 'Goodbye' },
{ target: 'fr', name: 'French', register: 'formal', model: 'gemini-2.5-flash' },
{ cwd: process.cwd() }
);
// result = { greeting: 'Bonjour', farewell: 'Au revoir' }
Các thành phần Export có sẵn
| Export | Chức năng |
|---|---|
TranslationMethod | Lớp cơ sở (base class) cho tất cả các phương thức |
LLMMethod | Lớp cơ sở cho các phương thức LLM (OpenRouter) |
DirectLLMMethod | Lớp cơ sở cho các nhà cung cấp LLM trực tiếp (OpenAI, Anthropic, Gemini) |
OpenAIMethod, AnthropicMethod, GeminiMethod | Các lớp nhà cung cấp LLM trực tiếp |
DeepLMethod, MicrosoftTranslatorMethod, LibreTranslateMethod | Các lớp dịch máy (MT) truyền thống |
GoogleTranslateMethod | Google Cloud Translation |
LLMCoachedMethod | Coached LLM (OpenRouter + dữ liệu huấn luyện) |
APIMethod | Client API từ xa |
runSync, runContentSync | Pipeline đồng bộ hóa đầy đủ |
resolveConfig, resolvePairs | Phân giải cấu hình |
validateTranslations | Cổng kiểm định chất lượng (quality gate) |
loadCoachingData, findDictionaryMatches | Các tiện ích huấn luyện (coaching) |
Mở rộng nhà cung cấp tùy chỉnh
Kế thừa DirectLLMMethod để thêm một nhà cung cấp LLM mới trong khoảng 40 dòng mã:
import { DirectLLMMethod } from 'champollion';
class MistralMethod extends DirectLLMMethod {
constructor(options) {
super(options);
this.name = 'mistral';
}
_getApiKeyEnvVar() { return 'MISTRAL_API_KEY'; }
_getApiKeyOptionsKey() { return 'mistralApiKey'; }
_getDefaultModel() { return 'mistral-large-latest'; }
_getProviderLabel() { return 'Mistral'; }
_buildApiRequest({ prompt, systemMessage, apiKey, model, temperature }) {
return {
url: 'https://api.mistral.ai/v1/chat/completions',
headers: { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
body: {
model,
messages: [
...(systemMessage ? [{ role: 'system', content: systemMessage }] : []),
{ role: 'user', content: prompt },
],
temperature,
},
};
}
_extractResponseText(json) {
return json.choices?.[0]?.message?.content;
}
// Optional but recommended: provider-specific setup help when translation fails
getSetupHelp() {
if (!process.env.MISTRAL_API_KEY) {
return [
'',
' ┌─ Missing API Key ─────────────────────────────────────────────┐',
' │ Mistral requires an API key from https://console.mistral.ai │',
' │ Run: export MISTRAL_API_KEY=... │',
' └────────────────────────────────────────────────────────────────┘',
];
}
return [' API key is set but translation failed. Check your Mistral dashboard.'];
}
}
Bạn sẽ nhận được các tính năng dịch (translate), huấn luyện (coaching), vòng lặp thử lại (retry loops), xác thực mô hình, phân cấp chất lượng và hỗ trợ thiết lập hoàn toàn miễn phí. Chỉ có cấu trúc yêu cầu HTTP là đặc thù của từng nhà cung cấp. Đối với các adapter không phải LLM sử dụng fetch() thô, hãy sử dụng helper fetchWithRetry() dùng chung từ lib/methods/fetch-with-retry.js thay vì tự viết vòng lặp thử lại của riêng bạn.
Xem thêm
- Tài liệu tham khảo CLI — tất cả các lệnh và cờ
- Phương thức dịch — lựa chọn và kết hợp các phương thức
- Translation Memory — bộ nhớ đệm và tiết kiệm chi phí
- Làm việc với biên dịch viên chuyên nghiệp — quy trình làm việc với XLIFF
- Đặc tả Plugin — định dạng manifest của plugin phương thức
- Kiến trúc — cách các thành phần kết nối với nhau
- Ngôn ngữ được hỗ trợ — hỗ trợ ngôn ngữ tích hợp sẵn
- Cách hoạt động của đồng bộ hóa — pipeline dịch thuật