คู่มือ Agent: การใช้งาน champollion

champollion คือเครื่องมือ CLI ที่แปลไฟล์ locale ของแอปพลิเคชันของคุณด้วยคำสั่งเดียว คู่มือนี้จัดทำขึ้นสำหรับ AI agent (หรือนักพัฒนาที่ทำงานร่วมกับ AI agent) ที่ต้องการเริ่มต้นและได้ไฟล์ locale ที่แปลแล้วอย่างรวดเร็ว

:::tip คุ้นเคยอยู่แล้ว? หากต้องการเพียงคำสั่ง ข้ามไปที่ CLI Reference ได้เลย หากต้องการสร้างและทดสอบวิธีการแปล โปรดดู Arena Agent Guide :::

---

การตั้งค่าสภาพแวดล้อม

# No global install needed — npx runs it directly
npx champollion sync

ข้อกำหนด:

• Node.js 18+
• API key สำหรับผู้ให้บริการแปลภาษาของคุณ

การตั้งค่า API key — champollion ต้องการ key อย่างน้อยหนึ่งรายการขึ้นอยู่กับวิธีการที่คุณใช้:

# Option 1: export (session only)
export OPENROUTER_API_KEY="sk-or-..."        # for llm / llm-coached methods
export GOOGLE_TRANSLATE_API_KEY="AIza..."    # for google-translate method

# Option 2: .env file in your project root (persistent, gitignored)
echo 'OPENROUTER_API_KEY=sk-or-...' > .env

Champollion อ่าน .env โดยอัตโนมัติ รับ OpenRouter key ได้ที่ openrouter.ai/keys

---

การ Sync ครั้งแรก

Champollion ตรวจจับไฟล์ locale, รูปแบบไฟล์ (JSON, TOML, YAML, PO) และภาษาเป้าหมายของคุณโดยอัตโนมัติ:

npx champollion sync

สิ่งที่เกิดขึ้น:

1. โหลด champollion.config.json (หรือตรวจจับการตั้งค่าอัตโนมัติ)
2. สแกนไฟล์ locale ต้นฉบับ และทำให้ key ที่ซ้อนกันแบนราบ
3. เปรียบเทียบกับ .champollion.lock (แฮช SHA-256 ของค่าที่แปลไปก่อนหน้า)
4. ตรวจสอบ .champollion/tm.json สำหรับการแปลที่แคชไว้ (Translation Memory)
5. แปลเฉพาะ key ที่เปลี่ยนแปลง, ขาดหายไป หรือล้าสมัย ผ่านวิธีการที่กำหนดไว้
6. รัน quality gate (5 การตรวจสอบ) สำหรับทุกการแปล
7. เขียนการแปลที่ผ่านการตรวจสอบลงในไฟล์ locale เป้าหมาย
8. อัปเดต lock file และ TM cache

ในการรันซ้ำทั่วไปหลังจากเปลี่ยน key หนึ่งรายการ ขั้นตอนที่ 4 จะดึง 142 key จาก cache และขั้นตอนที่ 5 จะแปลเพียง 1 key นี่คือเหตุผลที่การ sync ครั้งถัดไปรวดเร็วและประหยัดค่าใช้จ่าย

---

การกำหนดค่า

สร้าง champollion.config.json ในไดเรกทอรีรากของโปรเจกต์:

{
  "inputLocale": "en",
  "pairs": {
    "en-fr": { "method": "llm-coached" },
    "en-ja": { "method": "google-translate" },
    "en-crk": { "method": "api", "endpoint": "http://localhost:3000/translate" }
  }
}

ฟิลด์หลัก:

ฟิลด์	วัตถุประสงค์	ค่าเริ่มต้น
inputLocale	ภาษาต้นฉบับ	en
pairs	แผนที่ต้นฉบับ→เป้าหมายพร้อมการกำหนดค่าวิธีการ	(จำเป็น)
localesDir	ตำแหน่งที่เก็บไฟล์ locale	(ตรวจจับอัตโนมัติ)
model	โมเดล LLM สำหรับวิธีการ llm/llm-coached	google/gemini-2.5-flash
batchSize	จำนวน key ต่อการเรียก API หนึ่งครั้ง	80 (LLM), 128 (Google)
jsonConcurrency	การแปล locale แบบขนานสำหรับ JSON key	200
contentConcurrency	การเรียก API แบบขนานสำหรับการแปลเนื้อหา	48

ข้อมูลอ้างอิงฉบับเต็ม: Configuration

---

วิธีการแปล

วิธีการ	เมื่อใดควรใช้	ค่าใช้จ่าย	API key ที่ต้องการ
llm	ใช้งานทั่วไป เหมาะสำหรับภาษาที่มีทรัพยากรมาก	คิดตาม token (ขึ้นอยู่กับโมเดล)	OPENROUTER_API_KEY
llm-coached	เมื่อมีกฎไวยากรณ์/พจนานุกรมสำหรับภาษาเป้าหมาย	คิดตาม token + บริบทการสอน	OPENROUTER_API_KEY
google-translate	ภาษาที่มีทรัพยากรสูงซึ่ง GT ทำงานได้ดี	$20/ล้านตัวอักษร	GOOGLE_TRANSLATE_API_KEY
api	Pipeline แบบกำหนดเองที่โฮสต์ผ่าน HTTP endpoint	ขึ้นอยู่กับเซิร์ฟเวอร์	ไม่มี (endpoint จัดการการยืนยันตัวตน)
plugin	วิธีการที่บรรจุไว้ล่วงหน้าและติดตั้งในเครื่อง	แตกต่างกันไป	แตกต่างกันไป

รายละเอียด: Translation Methods

---

Coaching Data

สำหรับคู่ llm-coached coaching data จะชี้นำ LLM ด้วยความรู้ทางภาษาศาสตร์ที่ชัดเจน สร้างไฟล์ coaching:

coaching/fr.json

{
  "grammar_rules": [
    "Use formal register (vous) for all UI text",
    "Adjectives agree in gender and number with the noun"
  ],
  "dictionary": {
    "dashboard": "tableau de bord",
    "settings": "paramètres"
  },
  "style_notes": "Prefer active voice. Avoid anglicisms."
}

อ้างอิงในการกำหนดค่าคู่ภาษาของคุณ:

"en-fr": { "method": "llm-coached", "coachingFile": "coaching/fr.json" }

Quality gate จะตรวจสอบว่าคำศัพท์ในพจนานุกรมปรากฏในผลลัพธ์จริง — การละเมิดจะถูกบันทึกเป็นคำเตือน [TERM]

รายละเอียด: Coaching Data

---

Quality Gate

ทุกการแปลจะผ่านการตรวจสอบอัตโนมัติห้ารายการก่อนที่จะเขียนลงดิสก์:

การตรวจสอบ	สิ่งที่ตรวจจับ	ตัวอย่าง
ว่างเปล่า/ไม่มีเนื้อหา	โมเดลไม่ส่งคืนผลลัพธ์	""
Source echo	โมเดลส่งคืนข้อความภาษาอังกฤษต้นฉบับโดยไม่เปลี่ยนแปลง	"Welcome" สำหรับภาษาญี่ปุ่น
Hallucination loop	trigram ที่ซ้ำกัน	"Qo' Qo' Qo' Qo'"
Length inflation	ผลลัพธ์ยาวกว่าต้นฉบับ 4 เท่าขึ้นไป	ต้นฉบับ 10 ตัวอักษร → ผลลัพธ์ 50 ตัวอักษร
Script compliance	สคริปต์ไม่ถูกต้องสำหรับ locale	ข้อความ Latin สำหรับ locale ภาษาอาหรับ

ความล้มเหลวจะถูกบันทึกด้วยคำนำหน้า [GATE] ไม่มี silent fallback — หากการแปลล้มเหลว จะถูกรายงาน ไม่ใช่ยอมรับโดยไม่แจ้ง

รายละเอียด: Quality Gate

---

Translation Memory

Champollion แคชการแปลไว้ใน .champollion/tm.json โดยใช้ข้อความต้นฉบับ + locale + วิธีการเป็น key ในการ sync ครั้งถัดไป key ที่ไม่เปลี่ยนแปลงจะถูกดึงจาก cache — ไม่มีการเรียก API ไม่มีค่าใช้จ่าย

[TM] 142 key(s) served from cache
Translating 3 key(s) to French (llm)... [OK]

หากต้องการข้ามการใช้ cache สำหรับการรันครั้งเดียว: npx champollion sync --no-tm

รายละเอียด: Translation Memory

---

ไฟล์ที่สร้างขึ้น

Champollion สร้างไฟล์หลายรายการในโปรเจกต์ของคุณ ควรทำความเข้าใจว่าแต่ละไฟล์คืออะไร เพื่อไม่ให้ลบหรือ commit ผิดพลาด:

ไฟล์	วัตถุประสงค์	Git?
.champollion.lock	แฮช SHA-256 ของค่าต้นฉบับที่แปลแล้ว (สำหรับตรวจจับการเปลี่ยนแปลง)	ใช่ — commit ไฟล์นี้
.champollion-content.lock	เหมือนกัน แต่สำหรับไฟล์เนื้อหา Markdown/MDX	ใช่ — commit ไฟล์นี้
.champollion/tm.json	Translation Memory cache	ใช่ — commit ไฟล์นี้ (ช่วยประหยัดค่า API สำหรับทีม)
.champollion/coaching/	ไดเรกทอรี coaching data	ใช่ — นี่คือความรู้ทางภาษาศาสตร์ของคุณ
champollion.config.json	การกำหนดค่าโปรเจกต์	ใช่ — commit ไฟล์นี้

---

รูปแบบการใช้งานทั่วไป

แปลคู่ภาษาเดียว:

npx champollion sync --pair en-fr

แปลทุกคู่ที่กำหนดไว้:

npx champollion sync

Champollion แปล locale ทั้งหมดแบบขนาน ด้วย TM caching เฉพาะ key ที่เปลี่ยนแปลงเท่านั้นที่จะเรียก API

โหมดเนื้อหา (Markdown/MDX สำหรับ Docusaurus, Hugo ฯลฯ):

npx champollion sync --content

แปลเอกสาร บทความบล็อก และไฟล์เนื้อหาควบคู่กับ locale JSON ใช้การทำงานแบบขนาน (ค่าเริ่มต้น: 48 การเรียก API พร้อมกัน) ปรับแต่งด้วย --content-concurrency

Dry run (ดูตัวอย่างโดยไม่เขียนไฟล์):

npx champollion sync --dry-run

บังคับแปลซ้ำสำหรับ key ที่ระบุ:

npx champollion sync --force-keys "hero.title,nav.about"

บังคับแปลซ้ำไฟล์เนื้อหาทั้งหมด:

npx champollion sync --force-content

ตรวจสอบสถานะการแปล:

npx champollion status

แสดงความครอบคลุม, ระดับคุณภาพ และข้อมูล plugin สำหรับแต่ละคู่ภาษา

ตรวจสอบ fallback ที่ยังไม่ได้แปล:

npx champollion audit

แสดงรายการค่า fallback [EN] ทั้งหมดที่ยังต้องการการแปล

---

การแก้ไขปัญหา

ปัญหา	วิธีแก้ไข
OPENROUTER_API_KEY not set	Export key หรือเพิ่มลงใน .env ในไดเรกทอรีรากของโปรเจกต์
No locale files found	ตั้งค่า localesDir ในการกำหนดค่า หรือตรวจสอบให้แน่ใจว่าไฟล์ locale ของคุณตรงกับการตั้งชื่อมาตรฐาน (en.json, fr.json)
[GATE] Script compliance failed	locale เป้าหมายของคุณได้รับข้อความ Latin แทนสคริปต์ที่คาดหวัง — ลองใช้โมเดลอื่นหรือเพิ่ม coaching data
[GATE] Source echo	โมเดลส่งคืนภาษาอังกฤษโดยไม่เปลี่ยนแปลง — coaching data หรือโมเดลอื่นมักแก้ปัญหานี้ได้
การแปลทั้งหมดถูกแคช	รันด้วย --no-tm เพื่อข้าม cache หรือ --force-keys สำหรับ key ที่ระบุ
Lock file conflicts	.champollion.lock ใช้แฮช SHA-256 — merge conflict สามารถแก้ไขได้อย่างปลอดภัยโดยเลือกเวอร์ชันใดเวอร์ชันหนึ่ง จากนั้นรัน sync ใหม่

---

ขั้นตอนถัดไป

• Quick Start — คำแนะนำการเริ่มต้นใช้งานฉบับสมบูรณ์
• CLI Reference — ทุกคำสั่งและ flag
• How It Works — อธิบาย sync pipeline
• The Eval Harness Bridge — วิธีที่ champollion เชื่อมต่อกับ Arena
• ต้องการสร้างวิธีการแปลของคุณเอง? ดู Arena Agent Guide — สร้างวิธีการ พิสูจน์ว่าใช้งานได้ และรับรางวัล