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

Kiến trúc

Hệ sinh thái dịch thuật Champollion gồm ba công cụ độc lập hoạt động cùng nhau thông qua các giao ước (contract) được định nghĩa rõ ràng. Không công cụ nào phụ thuộc vào nhau tại thời điểm build. Chúng giao tiếp thông qua một định dạng plugin phương thức chung và một giao ước REST API.

Ba thành phần​

champollion (dự án này)​

Công cụ mã nguồn mở dành cho nhà phát triển. Dịch các tệp locale bằng các phương thức có thể cắm (pluggable). Không phụ thuộc (zero dependencies), cấu hình tùy chọn, hoạt động ngay khi cài đặt.

Các phương thức tích hợp sẵn:

  • llm → OpenRouter / bất kỳ LLM nào (hơn 200 mô hình)
  • llm-coached → LLM + hướng dẫn ngữ pháp/từ điển
  • openai → API OpenAI trực tiếp (GPT-4o, GPT-4o-mini)
  • anthropic → API Anthropic trực tiếp (Claude Sonnet, Haiku, Opus)
  • gemini → API Google Gemini trực tiếp (Flash, Pro — có gói miễn phí)
  • google-translate → Google Cloud Translation API v2
  • deepl → API DeepL hỗ trợ bảng thuật ngữ (glossary)
  • microsoft-translator → Azure Cognitive Services Translator
  • libretranslate → LibreTranslate tự lưu trữ (self-hosted) (AGPL, miễn phí)
  • api → Đường truyền tinh gọn (thin pipe) đến bất kỳ endpoint REST từ xa nào

Eval Harness (dự án đồng hành)​

Một công cụ nghiên cứu để phát triển, thử nghiệm và đánh giá hiệu năng (benchmark) các phương thức dịch thuật. Khi một phương thức đạt chất lượng chấp nhận được, harness sẽ xuất ra một plugin phương thức — một tệp manifest method.json và các tệp dữ liệu hướng dẫn tùy chọn.

Harness không bao giờ chạy bên trong champollion. Đây là một công cụ riêng biệt tạo ra đầu ra tĩnh (các tệp JSON). Champollion chỉ đọc các tệp đó.

→ Eval Harness trên GitHub

Champollion Translate (dự kiến)​

Một dịch vụ API tính phí theo mức sử dụng (metered API) lưu trữ các phương thức dịch thuật độc quyền ở phía máy chủ — các prompt, dữ liệu hướng dẫn và quy trình ngôn ngữ (linguistic pipeline) không bao giờ rời khỏi máy chủ.

Cách chúng kết nối​

Eval Harness → champollion (xuất một chiều)​

Giao ước: Đặc tả Plugin

Champollion Translate → champollion (API khi chạy)​

APIMethod của Champollion là một đường truyền đơn thuần (dumb pipe). Nó gửi các key đi và nhận lại bản dịch. Nó không chứa bất kỳ logic dịch thuật hay nội dung độc quyền nào.

Những gì mỗi thành phần biết về nhau​

Công cụBiết về champollion?Biết về Champollion Translate?Biết về harness?
champollion(chính là champollion)Có — phương thức api gọi nóKhông — chỉ đọc dữ liệu xuất của plugin
Champollion TranslateCó — phục vụ các yêu cầu của nó(chính là Champollion Translate)Không — nhận các phương thức đã triển khai
Eval HarnessCó — xuất định dạng pluginKhông — các phương thức được triển khai riêng biệt(chính là harness)

Các kịch bản sử dụng​

Kịch bản 1: Miễn phí, không cần cấu hình (hầu hết người dùng)​

export OPENROUTER_API_KEY=sk-...
npx champollion sync

Sử dụng phương thức llm tích hợp sẵn. Không cần plugin, không cần Champollion Translate, không cần harness.

Kịch bản 2: Bản dịch cơ sở từ Google Translate​

export GOOGLE_TRANSLATE_API_KEY=AIza...
npx champollion sync

Sử dụng phương thức google-translate tích hợp sẵn. Không cần plugin.

Kịch bản 3: Plugin mở đi kèm hướng dẫn​

champollion plugin install ./french-formal-v1/
champollion sync

Plugin có type: "llm-coached" → champollion sử dụng khóa OpenRouter của chính người dùng. Dữ liệu hướng dẫn được lưu cục bộ (không gọi máy chủ).

Kịch bản 4: Tự thiết lập hướng dẫn (không plugin, không harness)​

champollion.config.json
{
  "pairs": {
    "en:fr": { "method": "llm-coached" }
  }
}

Người dùng tự duy trì các quy tắc ngữ pháp và từ điển của riêng họ trong .champollion/coaching/fr.json.

Thẻ Ngôn ngữ (Language Cards)​

Mỗi ngôn ngữ trong champollion được cấu hình thông qua một Thẻ Ngôn ngữ (Language Card) — một tệp JSON thống nhất chứa các thiết lập sẵn về văn phong (register preset), quy tắc mức độ trang trọng (formality), cờ hỗ trợ phương thức, quy ước trình bày văn bản (typography), phân loại phả hệ ngôn ngữ và dữ liệu tham chiếu ngôn ngữ học.

Các thẻ được tải ngay lập tức (eagerly) khi import. Mỗi thẻ chứa tất cả siêu dữ liệu (metadata) mà công cụ dịch thuật và tài liệu dành cho nhà phát triển cần — không có tầng tham chiếu riêng biệt. Các thẻ được tạo từ các nguồn uy tín (IANA, CLDR, Glottolog, WALS) bằng cách sử dụng scripts/generate-language-card.mjs và scripts/build-language-tree.mjs, sau đó được con người kiểm duyệt để đảm bảo tính chính xác về mặt ngôn ngữ học.

Nguyên tắc thiết kế​

  1. Không phụ thuộc vòng (circular dependencies). Các cầu nối là một chiều.
  2. Champollion là phần lõi gọn nhẹ. Không phụ thuộc, cấu hình tùy chọn. Các plugin và API là phần bổ sung.
  3. Bảo vệ sở hữu trí tuệ (IP) bằng kiến trúc. Các kỹ thuật độc quyền nằm ở phía máy chủ. Gói npm không đi kèm bất kỳ thứ gì độc quyền.
  4. Định dạng plugin là giao ước. Mọi thứ đều luân chuyển qua method.json.
  5. Mỗi công cụ có một nhiệm vụ duy nhất. Harness → phát triển phương thức. Champollion Translate → lưu trữ phương thức. Champollion → dịch tệp.

Xem thêm​