Bắt đầu nhanh

Dịch tệp ngôn ngữ (locale) đầu tiên của bạn trong 60 giây.

1. Thiết lập các tệp ngôn ngữ

Tạo một tệp ngôn ngữ nguồn. Champollion hỗ trợ JSON, TOML và YAML:

locales/en.json

{
  "hero": {
    "title": "Welcome to our platform",
    "subtitle": "Build something amazing"
  },
  "nav": {
    "home": "Home",
    "about": "About",
    "contact": "Contact"
  }
}

2. Thiết lập API Key

Chọn một nhà cung cấp và thiết lập key:

# Option A: OpenRouter (200+ models, recommended)
export OPENROUTER_API_KEY=sk-or-v1-...

# Option B: Gemini (free tier — zero cost to start)
export GEMINI_API_KEY=AI...

Nhận key Gemini miễn phí tại aistudio.google.com/apikey. Nhận key OpenRouter tại openrouter.ai.

3. Chạy đồng bộ (Sync)

npx champollion sync

:::tip Sử dụng Gemini? Nếu bạn chọn Tùy chọn B (Gemini), hãy thêm --method gemini:

npx champollion sync --method gemini

:::

Champollion sẽ:

1. Tự động phát hiện locales/en.json làm nguồn
2. Tìm (hoặc yêu cầu nhập) các ngôn ngữ đích
3. Dịch tất cả các key
4. Ghi vào locales/fr.json, locales/ja.json, v.v.
5. Tạo .champollion.lock để theo dõi những gì đã được dịch

4. Kiểm tra kết quả

cat locales/fr.json

{
  "hero": {
    "title": "Bienvenue sur notre plateforme",
    "subtitle": "Construisez quelque chose d'incroyable"
  },
  "nav": {
    "home": "Accueil",
    "about": "À propos",
    "contact": "Contact"
  }
}

Điều gì xảy ra tiếp theo?

Khi bạn thay đổi một chuỗi nguồn, Champollion sẽ phát hiện thay đổi đó thông qua việc theo dõi mã băm SHA-256 và chỉ dịch lại key đó trong lần đồng bộ tiếp theo:

locales/en.json (updated)

{
  "hero": {
    "title": "Welcome to Acme Platform",  // ← changed
    "subtitle": "Build something amazing"  // ← unchanged, skipped
  }
}

npx champollion sync
# Only "hero.title" is re-translated across all locales

Key không thay đổi (hero.subtitle) sẽ được lấy từ bộ nhớ đệm Translation Memory (Bộ nhớ dịch thuật) của Champollion — không cần gọi API, không tốn chi phí. Bộ nhớ đệm được xây dựng tự động trong mỗi lần đồng bộ và được lưu trữ tại .champollion/tm.json.

Tùy chọn: Tạo tệp cấu hình

Để kiểm soát nhiều hơn, hãy tạo một tệp cấu hình:

npx champollion init                         # guided wizard
npx champollion init --yes --langs fr,de,ja  # quick setup with specific targets

Trình hướng dẫn từng bước sẽ dẫn dắt bạn qua các register presets (thiết lập sẵn về văn phong) của từng ngôn ngữ — các hướng dẫn về giọng điệu/mức độ trang trọng được xây dựng sẵn và tinh chỉnh phù hợp với hệ thống ngôn ngữ đó. Tiếng Pháp có các thiết lập sẵn T-V (vouvoiement so với tutoiement), tiếng Hàn có các cấp độ kính ngữ (해요체 so với 합쇼체 so với 해체), tiếng Nhật có các tùy chọn keigo (です/ます so với 丁寧語).

Hoặc tạo tệp cấu hình thủ công với các key thiết lập sẵn:

champollion.config.json

{
  "version": 3,
  "inputLocale": "en",
  "localesDir": "./locales",
  "languages": {
    "fr": "casual-tu",
    "ko": "polite-haeyo",
    "ja": "polite"
  },
  "model": "google/gemini-2.5-flash"
}

Chạy npx champollion init để duyệt qua các thiết lập sẵn có cho từng ngôn ngữ.

Tùy chọn: Chế độ Watch (Theo dõi)

Tự động dịch khi tệp nguồn của bạn thay đổi:

npx champollion watch

Các bước tiếp theo

• Cấu hình — Tài liệu tham khảo cấu hình đầy đủ
• Phương thức dịch — Chọn phương thức phù hợp cho từng cặp ngôn ngữ
• Translation Memory — Cách bộ nhớ đệm giúp bạn tiết kiệm chi phí khi chạy lại
• Làm việc với biên dịch viên chuyên nghiệp — Xuất tệp XLIFF để con người soát lỗi
• Tích hợp Framework — Hugo, next-intl, react-i18next
• CI/CD — Tự động hóa việc dịch thuật trong pipeline của bạn
• Xử lý sự cố — Các vấn đề thường gặp và giải pháp