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

Tham chiếu CLI

Lệnh​

champollion init              Interactive setup wizard (--yes for quick defaults)
champollion sync              Translate & sync all locale files
champollion watch             Auto-sync when the source file changes
champollion audit             List all untranslated [EN] fallback values
champollion lint              Scan source code for hardcoded strings
champollion wrap              Auto-wrap hardcoded strings in t() calls (with undo)
champollion seo <sub>         Generate hreflang, sitemap.xml, or JSON-LD schema
champollion integrity         Audit locale files for format/encoding issues
champollion verify            Verify translations are present and correct (CI gate)
champollion status            Show pair configuration, plugins, and quality tiers
champollion provenance        Audit translation resource licensing
champollion plugin <sub>      Manage method plugins (install, remove, list)
champollion fonts <sub>       Download web fonts for PUA script converters
champollion leaderboard      Browse and install methods from the MT Eval Arena leaderboard
champollion tm <sub>          Manage Translation Memory cache (stats, clear)
champollion xliff <sub>       Export/import XLIFF 1.2 for professional review

Chạy champollion <command> --help để xem hướng dẫn chi tiết cho bất kỳ lệnh nào.

Tùy chọn toàn cục​

--help, -h              Show help (global or per-command)
--version, -v           Print version and exit
--yes, -y               Skip interactive prompts, use defaults
--config <path>         Custom config file path
--dir <path>            Override locales directory
--content-dir <path>    Hugo/Docusaurus content directory for Markdown translation
--source <code>         Override source locale (default: en)
--model <model>         Override translation model (full slug or alias from shared/model-aliases.json)
--method <method>       Translation method: llm, google-translate (default: from config)
--temperature <n>       LLM temperature (0.0–2.0, default: 0.3)
--coaching-file <path>  Path to free-text coaching prompt file (injected into system prompt)
--format <fmt>          Locale file format: json, toml, yaml, or auto
--dry, --dry-run        Preview changes without writing files
--concurrency <n>       Max parallel API calls (sets both JSON and content, default: 48)
--json-concurrency <n>  Max parallel locale translations for JSON keys (default: 200)
--content-concurrency <n> Max parallel API calls for content translation (default: 48)
--force-content         Re-translate all content files (clears content lock)
--force-keys <keys>     Comma-separated dot-notation keys to force re-translate
--no-tm                 Skip Translation Memory cache for this sync run
--no-verify             Skip post-sync verification pass
--locale <code>         Target locale (xliff export, tm clear)
--quiet                 Errors and warnings only — suppress banner, progress bar, and info lines
--json                  Machine-readable NDJSON output — one JSON object per event

init​

Trình hướng dẫn thiết lập tương tác giúp tạo champollion.config.json. Hướng dẫn bạn thiết lập ngôn ngữ nguồn, ngôn ngữ đích, định dạng tệp và mô hình dịch thuật.

champollion init                          # interactive wizard
champollion init --yes                    # skip wizard, use defaults
champollion init --yes --langs fr,de,ja   # quick setup with specific languages
champollion init --source en --dir ./i18n # overrides with defaults

Tùy chọn --langs: Danh sách các mã ngôn ngữ đích, phân tách bằng dấu phẩy. Bỏ qua bước hỏi ngôn ngữ và áp dụng các thiết lập sẵn (preset) về văn phong mặc định cho từng ngôn ngữ. Kết hợp với --yes để thiết lập hoàn toàn không tương tác.

Thiết lập sẵn ngôn ngữ (Language presets): Khi được hỏi về ngôn ngữ đích, bạn có thể nhập tên các thiết lập sẵn:

  • european → fr, de, es, it, pt, nl
  • asian → ja, zh, ko
  • global → fr, es, de, ja, zh, ko, pt, ar
  • nordic → da, fi, nb, sv

Kết hợp các thiết lập sẵn và mã ngôn ngữ riêng lẻ: european, ja → fr, de, es, it, pt, nl, ja

sync​

Dịch các khóa bị thiếu và lỗi thời trên tất cả các tệp ngôn ngữ. Chạy xác minh sau khi đồng bộ hóa theo mặc định.

champollion sync                                   # translate everything
champollion sync --dry-run                         # preview only
champollion sync --force-keys "hero.title"         # force re-translate
champollion sync --force-keys "a.title,a.subtitle" # multiple keys
champollion sync --force-content                   # re-translate all Markdown/MDX
champollion sync --content-dir ./content           # include Hugo Markdown
champollion sync --method google-translate          # force Google Translate
champollion sync --concurrency 20                  # 20 parallel API calls (both phases)
champollion sync --json-concurrency 30              # 30 parallel locale translations (JSON)
champollion sync --content-concurrency 8            # 8 parallel content translations
champollion sync --no-verify                        # skip post-sync verification
champollion sync --no-tm                            # skip cache, fresh API calls

Bộ nhớ dịch thuật (Translation Memory): Theo mặc định, sync sẽ tải .champollion/tm.json và cung cấp các bản dịch đã được lưu trong bộ nhớ đệm (cache) cho các giá trị nguồn không thay đổi. Sử dụng --no-tm để bỏ qua bộ nhớ đệm (hữu ích khi chuyển đổi nhà cung cấp dịch thuật hoặc gỡ lỗi chất lượng). Xem Bộ nhớ dịch thuật.

Phát hiện thay đổi: Champollion lưu trữ các mã băm SHA-256 trong .champollion.lock. Khi các giá trị nguồn thay đổi, lần đồng bộ tiếp theo sẽ tự động dịch lại các khóa đó. Hãy commit tệp lock để tất cả các nhà phát triển chia sẻ cùng một bản cơ sở (baseline).

Xử lý song song: Cả việc dịch khóa JSON và dịch nội dung đều chạy song song. Các tệp ngôn ngữ JSON được dịch đồng thời (mặc định: 200 ngôn ngữ đồng thời), với các lô (batch) trong mỗi ngôn ngữ cũng được xử lý song song (4 lô đồng thời). Việc dịch nội dung (Markdown, MDX, bài viết blog) chạy trong một nhóm công việc phẳng (mặc định: 48 cuộc gọi API đồng thời). Ghi đè bằng --json-concurrency, --content-concurrency, hoặc --concurrency (thiết lập cả hai).

Đầu ra: Quá trình đồng bộ hiển thị biểu ngữ phiên bản, phát hiện định dạng/framework, ước tính chi phí và thanh tiến trình cho từng ngôn ngữ:

champollion v0.1.0

[INFO] Detected format: json (auto)
[INFO] Source: en.json (2,847 keys)
[INFO] Pairs: es-MX:llm, fr:deepl

[INFO] es-MX.json — 2,847 missing
     ████████████████████████████████ 2,847/2,847 keys
[INFO] fr.json — 2,847 missing
     ████████████████████████████████ 2,847/2,847 keys
[OK] Synced 5,694 keys total.

Các thanh tiến trình cập nhật trực tiếp tại chỗ sau mỗi lô (~80 khóa). Sử dụng --quiet để chỉ hiển thị lỗi/cảnh báo, hoặc --json để xuất đầu ra NDJSON có thể đọc được bằng máy. Cả hai tùy chọn này đều ẩn thanh tiến trình và biểu ngữ.

watch​

Tự động đồng bộ hóa khi tệp ngôn ngữ nguồn thay đổi. Chạy cho đến khi bị ngắt bằng Ctrl+C.

champollion watch

audit​

Liệt kê tất cả các giá trị dự phòng (fallback) chưa được dịch có tiền tố [EN] từ các lần chạy trước. Thoát với mã lỗi (exit code) 1 nếu tìm thấy bất kỳ giá trị nào — sử dụng như một cổng kiểm duyệt CI để dừng các bản build có bản dịch chưa hoàn tất.

champollion audit

verify​

Đọc lại tất cả các tệp ngôn ngữ từ đĩa và xác minh xem các bản dịch có thực sự tồn tại và chính xác hay không. Đây là cùng một quy trình xác minh tự động chạy ở cuối mỗi lệnh sync (trừ khi --no-verify được truyền vào).

champollion verify                    # verify all locale files
champollion verify --warn-only        # non-blocking
champollion verify && echo "All good" # CI gate

Những gì lệnh này kiểm tra:

  • Tính tương đồng của khóa — tất cả các khóa nguồn đều có mặt trong mỗi ngôn ngữ đích
  • Các dấu hiệu dự phòng [EN] từ các lần chạy trước
  • Các bản dịch trống
  • Tuân thủ hệ chữ viết — các ngôn ngữ không dùng chữ Latinh phải có bản dịch không chứa ký tự ASCII
  • Giữ nguyên trình giữ chỗ (placeholder) — các trình giữ chỗ ICU phải khớp với nguồn
  • Các vấn đề về mã hóa — dấu BOM, ký tự ẩn
  • Trùng lặp nguồn — các giá trị giống hệt với nguồn (cảnh báo)

lint​

Quét mã nguồn để tìm các chuỗi hiển thị cho người dùng bị viết cứng (hardcoded) mà đáng lẽ phải sử dụng các lệnh gọi dịch thuật i18n. Tự động phát hiện framework của bạn (next-intl, react-i18next, vue-i18n, Hugo).

champollion lint                    # exits 1 if issues found
champollion lint --warn-only        # always exits 0
champollion lint --src ./app        # custom source directory
champollion lint --min-length 4     # minimum string length to flag

Những gì lệnh này phát hiện:

  • Các chuỗi viết cứng trong văn bản JSX, placeholder, alt, aria-label, title
  • Các tệp có nội dung hiển thị cho người dùng nhưng không import framework i18n
  • Khóa chết (dead keys) — các khóa ngôn ngữ không được tham chiếu bởi bất kỳ tệp nguồn nào
  • Điểm độ bao phủ (coverage score) — tỷ lệ phần trăm các chuỗi được xử lý qua i18n

Ngoại lệ (Exclusions): Tạo .champollionignore trong thư mục gốc của dự án (các mẫu glob, ví dụ: .gitignore).

wrap​

Tự động bao bọc (wrap) các chuỗi viết cứng được phát hiện bởi lint trong các lệnh gọi t(). Tự động tạo các bản sao lưu trước khi sửa đổi tệp.

champollion wrap                    # auto-wrap with backup
champollion wrap --dry              # preview wrapping changes
champollion wrap --undo             # restore from .champollion-backup/

Các chốt an toàn:

  1. Kiểm tra trạng thái Git sạch (bỏ qua trong chế độ chạy thử - dry-run)
  2. Tự động sao lưu vào .champollion-backup/
  3. Xem trước thay đổi (diff) trước khi ghi vào mỗi tệp
  4. Hỗ trợ --undo để khôi phục từ bản sao lưu

seo​

Tạo các thành phần SEO cho các trang web đa ngôn ngữ.

champollion seo hreflang                                        # print hreflang tags
champollion seo sitemap --base-url https://example.com --out sitemap.xml
champollion seo jsonld --base-url https://example.com           # JSON-LD schema
Lệnh phụĐầu ra
hreflangCác thẻ <link rel="alternate" hreflang>
sitemapsitemap.xml đa ngôn ngữ
jsonldSchema ngôn ngữ WebSite dạng JSON-LD

integrity​

Phát hiện lỗi hỏng dữ liệu và sự sai lệch trong các tệp ngôn ngữ đã dịch.

champollion integrity               # exits 1 if issues found
champollion integrity --warn-only   # non-blocking

Những gì lệnh này kiểm tra:

  • Lỗi hỏng trình giữ chỗ (ví dụ: {name} có trong nguồn nhưng thiếu ở đích)
  • Các vấn đề về mã hóa (lỗi hiển thị ký tự - mojibake, Unicode không hợp lệ)
  • Các bản sao chưa dịch (giá trị đích giống hệt nguồn)
  • Các khóa mồ côi (các khóa ở đích không tồn tại ở nguồn)
  • Tính đầy đủ của các danh mục số nhiều trong ICU MessageFormat (ví dụ: tiếng Ả Rập cần 6 danh mục)

tm​

Quản lý bộ nhớ đệm của Bộ nhớ dịch thuật (.champollion/tm.json). TM lưu trữ các bản dịch trước đó và cung cấp chúng trong các lần đồng bộ tiếp theo thay vì gọi API.

champollion tm stats                  # show cache statistics
champollion tm clear                  # clear cache (with confirmation)
champollion tm clear --yes            # clear without confirmation
champollion tm clear --locale fr      # clear only French entries
Lệnh phụĐầu ra
statsSố lượng mục, kích thước tệp, phân tích chi tiết theo từng ngôn ngữ
clearXóa tệp bộ nhớ đệm (toàn bộ hoặc theo từng ngôn ngữ)
Tùy chọnTác dụng
--locale <code>Chỉ xóa các mục của một ngôn ngữ
--yesBỏ qua yêu cầu xác nhận

Xem Bộ nhớ dịch thuật để biết cách hoạt động của TM và khi nào cần xóa nó.

xliff​

Xuất và nhập các tệp XLIFF 1.2 để các dịch giả chuyên nghiệp soát lỗi. XLIFF là định dạng trao đổi phổ biến được hỗ trợ bởi các công cụ CAT như memoQ, SDL Trados và Phrase.

champollion xliff export --locale fr                   # export French XLIFF
champollion xliff export --locale ja --out ./review/   # custom output path
champollion xliff import .champollion/xliff/fr.xliff       # import reviewed file
champollion xliff import ./reviewed.xliff --dry        # preview import
Lệnh phụĐầu ra
exportTạo .xliff từ các tệp ngôn ngữ nguồn + đích
importGộp các bản dịch .xliff đã được soát lỗi vào các tệp ngôn ngữ
Tùy chọnTác dụng
--locale <code>Ngôn ngữ đích để xuất (bắt buộc)
--out <path>Đường dẫn đầu ra hoặc thư mục tùy chỉnh
--dryXem trước khi nhập mà không ghi vào tệp

Xem Làm việc với dịch giả chuyên nghiệp để biết quy trình làm việc đầy đủ.

status​

Hiển thị cấu hình cặp ngôn ngữ, các plugin đã cài đặt, các cấp chất lượng và điểm số benchmark.

champollion status

provenance​

Kiểm duyệt giấy phép tài nguyên dịch thuật cho tất cả các plugin đã cài đặt.

champollion provenance

plugin​

Quản lý các plugin phương thức dịch thuật. Plugin là các công thức dịch thuật được đóng gói sẵn và được cài đặt vào .champollion/methods/.

champollion plugin list                      # show installed plugins
champollion plugin install ./my-method/      # install from local directory
champollion plugin remove crk-coached-v1     # remove a plugin

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

leaderboard​

Duyệt, tìm kiếm và cài đặt các phương thức dịch thuật từ bảng xếp hạng MT Eval Arena leaderboard. Các phương thức được cài đặt từ bảng xếp hạng đi kèm với điểm số benchmark và cấu hình MethodConfig chuẩn đầy đủ — cấu hình chính xác được sử dụng trong quá trình đánh giá.

champollion leaderboard                          # show leaderboard
champollion leaderboard --pair en:fr             # filter by language pair
champollion leaderboard --install crk-coached-v8 # install a method plugin
champollion leaderboard --install crk-coached-v8 --apply  # install + patch config
Tùy chọnTác dụng
--pair <code>Lọc bảng xếp hạng theo cặp ngôn ngữ (ví dụ: en:fr)
--install <name>Cài đặt một plugin phương thức từ bảng xếp hạng
--applySau khi cài đặt, tự động thêm methodPlugin vào champollion.config.json

Quy trình làm việc của --apply: Khi bạn cài đặt bằng --apply, Champollion sẽ ghi plugin phương thức vào .champollion/methods/ và vá (patch) tệp champollion.config.json của bạn để sử dụng nó cho cặp ngôn ngữ liên quan. Đây là con đường nhanh nhất từ "phương thức nào có điểm số tốt nhất?" đến "tôi đang sử dụng nó trong môi trường production."

fonts​

Tải xuống và quản lý các phông chữ web PUA cho các bộ chuyển đổi chữ viết của ngôn ngữ nhân tạo (constructed language). Các ngôn ngữ sử dụng các ký tự thuộc Vùng sử dụng riêng - Private Use Area (Klingon, Sindarin, Kryptonian) cần các phông chữ web tùy chỉnh để hiển thị chữ viết của chúng. Lệnh này tải chúng xuống từ các kho lưu trữ mã nguồn mở đã được xác minh.

champollion fonts list                           # show needed fonts
champollion fonts install                        # download all needed fonts
champollion fonts install --css                  # also generate CSS snippet
champollion fonts install --dir ./public/fonts   # custom output directory
Lệnh phụĐầu ra
listHiển thị những phông chữ PUA nào cần thiết và trạng thái cài đặt của chúng
installTải xuống phông chữ cho các ngôn ngữ đã được cấu hình
Tùy chọnTác dụng
--dir <path>Ghi đè thư mục đầu ra của phông chữ (tự động phát hiện từ loại dự án)
--cssTạo một đoạn mã conlang-fonts.css cùng với các phông chữ
--config <path>Đường dẫn đến tệp cấu hình (được sử dụng để phát hiện ngôn ngữ nào cần phông chữ)

Tự động phát hiện: Thư mục đầu ra được suy luận từ cấu trúc dự án của bạn:

  • Docusaurus → static/fonts/ hoặc website/static/fonts/
  • Hugo → static/fonts/
  • Mặc định → public/fonts/

Các bộ chuyển đổi Unicode gốc (crk → chữ viết Cree Syllabics, sr → chữ viết Serbian Cyrillic) KHÔNG yêu cầu cài đặt phông chữ.

Xem Conlangs, Chữ viết & Chính tả để biết chi tiết đầy đủ về phông chữ PUA.

Quy trình ba lớp​

Sử dụng kết hợp lint, sync, và audit để có một quy trình i18n cực kỳ vững chắc:

package.json
{
  "scripts": {
    "i18n:lint": "champollion lint",
    "i18n:sync": "champollion sync",
    "i18n:audit": "champollion audit"
  }
}
LớpLệnhKhi nàoMục đích
LintlintTrước khi commit (Pre-commit)Chặn các commit chứa chuỗi viết cứng
SyncsyncSau khi commit (Post-commit) / CIDịch các khóa bị thiếu và thay đổi
VerifyverifySau khi đồng bộ (Post-sync) / CIXác nhận các bản dịch tồn tại và chính xác
AuditauditBước buildDừng triển khai (fail deployment) nếu bất kỳ ngôn ngữ nào có dấu hiệu [EN]

Xem thêm​