ข้ามไปยังเนื้อหาหลัก

Cookbook: แปล 30 ภาษา

ขยายโปรเจกต์จากไม่กี่ locale ไปสู่การรองรับระดับโลก Cookbook นี้จะพาคุณผ่านการเลือกวิธีการแปล การปรับต้นทุน และการผสานรวมกับ CI สำหรับการ deploy หลายภาษาจริง

สถานการณ์: คุณมีแอป SaaS ที่มี en, fr, es และต้องการเพิ่มอีก 27 ภาษาใน 3 ระดับคุณภาพที่แตกต่างกัน

ขั้นตอนที่ 1: จัดหมวดหมู่ภาษาของคุณ​

ไม่จำเป็นที่ทั้ง 30 ภาษาจะต้องใช้แนวทางเดียวกัน จัดกลุ่มตามคุณภาพของวิธีการที่มีอยู่:

ระดับภาษาวิธีการเหตุผล
ระดับ 1 — Premiumja, ko, zh, de, ptllm (GPT-4o)ตลาดมูลค่าสูง ไวยากรณ์ซับซ้อน
ระดับ 2 — Standardit, nl, pl, sv, da, fi, no, cs, ro, hu, el, tr, id, ms, th, vi, uk, bggoogle-translateปริมาณสูง รองรับดีโดย Google
ระดับ 3 — Coachedcrk, oj, mi, hawllm-coached + pluginsทรัพยากรน้อย ต้องการการบังคับใช้คำศัพท์เฉพาะ

ขั้นตอนที่ 2: กำหนดค่าแบบ Per-Pair​

champollion.config.json
{
  "version": 3,
  "inputLocale": "en",
  "localesDir": "./locales",
  "defaultMethod": "google-translate",
  "model": "google/gemini-3.5-flash",
  "languages": {
    "ja": { "name": "Japanese", "register": "Polite/formal" },
    "ko": { "name": "Korean", "register": "Formal" },
    "zh": { "name": "Simplified Chinese", "register": "Neutral" },
    "de": { "name": "German", "register": "Formal (Sie)" },
    "pt": { "name": "Brazilian Portuguese", "register": "Informal" },
    "crk": { "name": "Plains Cree (SRO)", "register": "Neutral" }
  },
  "pairs": {
    "en:ja": { "method": "llm", "model": "openai/gpt-4o" },
    "en:ko": { "method": "llm", "model": "openai/gpt-4o" },
    "en:zh": { "method": "llm", "model": "openai/gpt-4o" },
    "en:de": { "method": "llm", "model": "openai/gpt-4o" },
    "en:pt": { "method": "llm", "model": "openai/gpt-4o" },
    "en:crk": { "methodPlugin": "crk-coached-v1" }
  }
}

หมายเหตุ: ภาษาที่ไม่ได้ระบุใน pairs จะสืบทอด defaultMethod: "google-translate" คุณไม่จำเป็นต้องระบุทั้ง 30 ภาษา

ข้อมูล

การรองรับ crk อยู่ระหว่างการพัฒนา — ดู รองรับภาษาที่มีทรัพยากรน้อย สำหรับสถานะและแนวทางการมีส่วนร่วม

ขั้นตอนที่ 3: ตั้งค่า API Keys​

คุณจะต้องใช้ API keys ทั้งสองสำหรับการกำหนดค่านี้:

export OPENROUTER_API_KEY="sk-or-v1-..."
export GOOGLE_TRANSLATE_API_KEY="AIza..."

ขั้นตอนที่ 4: ทดลอง Dry Run ก่อน​

ควรดูตัวอย่างเสมอก่อนแปล 30 ภาษา:

npx champollion sync --dry

ตรวจสอบผลลัพธ์ ซึ่งจะแสดง:

  • คู่ภาษาใดใช้วิธีการใด
  • จำนวน key ที่ใหม่หรือเปลี่ยนแปลงต่อ locale
  • จำนวน API calls โดยประมาณต่อระดับ

ขั้นตอนที่ 5: รัน Sync​

npx champollion sync

Champollion ประมวลผลแต่ละคู่ภาษาอย่างอิสระ คู่ระดับ 2 ที่ใช้ Google Translate จะเร็วกว่า คู่ระดับ 1 ที่ใช้ LLM จะช้ากว่าแต่มีคุณภาพสูงกว่า คู่ระดับ 3 แบบ coached จะใช้ข้อมูล coaching ของ plugin

การอัปเดตแบบ Incremental​

หลังจาก sync ครั้งแรก การรันครั้งถัดไปจะแปลเฉพาะ key ที่ เปลี่ยนแปลงหรือใหม่ เท่านั้น:

# Only keys that changed since last sync
npx champollion sync

Lock file (.champollion.lock) ติดตามสิ่งที่แปลไปแล้ว ดังนั้นคุณจะไม่แปลเนื้อหาที่คงที่ซ้ำอีก

ขั้นตอนที่ 6: ตรวจสอบคุณภาพ​

ตรวจสอบสถานะของคู่ภาษาทั้งหมด:

npx champollion status

ผลลัพธ์จะแสดงตารางที่แสดงวิธีการ โมเดล ระดับคุณภาพ และข้อมูล coaching หรือคะแนน benchmark ของแต่ละคู่

ผลลัพธ์เป็นไปตาม register ที่กำหนดหรือไม่?​

ในขั้นตอนที่ 2 คุณได้ประกาศ register ต่อภาษา — "Polite/formal" สำหรับภาษาญี่ปุ่น "Formal (Sie)" สำหรับภาษาเยอรมัน (ยังไม่คุ้นกับคำนี้? อ่านคำอธิบายในภาษาที่เข้าใจง่ายได้ที่ glossary) คำสั่งเหล่านั้นจะถูกส่งเข้าไปใน prompt การแปล แต่ prompt คือการร้องขอ ไม่ใช่การรับประกัน

MT Eval Arena harness — เครื่องมือเดียวกับที่ขับเคลื่อน leaderboard สาธารณะ — สามารถวัดการปฏิบัติตาม register และสไตล์จากตัวอย่างการแปลของคุณได้ เมตริกด้านสไตล์การเขียนจะตรวจสอบผลลัพธ์แต่ละรายการเทียบกับ register ที่คาดหวัง (ตัวบ่งชี้ formal/informal, สรรพนาม T–V, การย่อคำ, การเปลี่ยนแปลงความยาวประโยค) และรายงาน style_consistency_rate ตลอดการรัน คุณยังสามารถชี้ไปที่โปรไฟล์ brand voice แบบกำหนดเองด้วย --style-profile

# install the harness, then run your sample corpus through it
curl -fsSL champollion.dev/harness | bash
mt-eval run --corpus my-sample.json --style-profile brand-voice.json

ข้อควรระวังสองประการ: เมตริกเหล่านี้เป็น ข้อมูลเชิงอ้างอิง (ไม่เคยเข้าสู่คะแนนรวมของ leaderboard) และการตรวจจับ formality อิงจาก marker — เป็นตัวตรวจจับการเบี่ยงเบน ไม่ใช่การตัดสินของมนุษย์ รายละเอียดและนิยามเมตริก: เมตริกสไตล์การเขียนและ register

ขั้นตอนที่ 7: การผสานรวมกับ CI​

เพิ่มลงใน GitHub Actions workflow เพื่อให้การแปลอัปเดตอยู่เสมอในทุก push:

.github/workflows/i18n-sync.yml
name: Sync Translations
on:
  push:
    paths:
      - 'locales/en/**'

jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - run: npm ci

      - name: Sync translations
        run: npx champollion sync
        env:
          OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
          GOOGLE_TRANSLATE_API_KEY: ${{ secrets.GOOGLE_TRANSLATE_API_KEY }}

      - name: Commit updated translations
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add locales/
          git diff --staged --quiet || git commit -m "chore(i18n): sync translations"
          git push

การประมาณต้นทุน​

สำหรับโปรเจกต์ที่มี 500 source keys ใน 30 ภาษา:

ระดับภาษาวิธีการต้นทุนโดยประมาณ
ระดับ 1 (5 ภาษา)ja, ko, zh, de, ptGPT-4o~$2.50/full sync
ระดับ 2 (18 ภาษา)it, nl, pl, etc.Google Translate~$0.90/full sync
ระดับ 3 (4 ภาษา)crk, oj, mi, hawGPT-4o-mini coached~$0.40/full sync
รวม30 ภาษาMixed~$3.80/full sync

Incremental syncs (5–20 key ที่เปลี่ยนแปลง) มีต้นทุนเพียงเศษเสี้ยวของ full sync

ดูเพิ่มเติม​