Lumaktaw sa pangunahing nilalaman

Tutorial: Bumuo ng Translation Plugin

Bumuo ng custom na paraan ng pagsasalin mula sa simula, i-benchmark ito, at i-deploy bilang champollion plugin. Ito ang kumpletong workflow para sa pagdaragdag ng bagong pares ng wika na hindi sinusuportahan ng anumang handa nang API.

Ang bubuuin ninyo: Isang translation plugin na may coaching para sa pormal na French na may ipinatutupad na terminolohiya, mga tuntunin sa gramatika, at benchmark scores.

Oras: 30–45 minuto

Mga kinakailangan:

  • naka-install ang champollion (npm install --save-dev champollion)
  • Isang OpenRouter API key (OPENROUTER_API_KEY)
  • Python 3.10+ (para sa eval harness)

Hakbang 1: Tukuyin ang Problema​

Nagsasalin po kayo ng SaaS dashboard sa French. Ang default na paraang llm ay lumilikha ng tama ngunit hindi magkakatugmang mga pagsasalin:

  • Minsan ang "dashboard" ay nagiging "tableau de bord," at sa ibang pagkakataon ay "panneau de contrôle"
  • Ang tono ay nagpapalit-palit sa pagitan ng mga anyong tu at vous
  • Ang mga teknikal na termino ay hindi magkakatugmang nagiging anglicized

Kailangan ninyo ng pagpapatupad ng terminolohiya at kontrol sa register na hindi ibinibigay ng generic na LLM prompt.

Hakbang 2: Gumawa ng Coaching Data​

Gumawa ng coaching file na nag-e-encode ng inyong mga kinakailangang pangwika:

mkdir -p .champollion/coaching
.champollion/coaching/fr.json
{
  "grammar_rules": [
    "Always use the 'vous' form for formal register",
    "French adjectives agree in gender and number with their noun",
    "Use the present tense for UI instructions, not the imperative",
    "Preserve sentence-final punctuation style from the source"
  ],
  "dictionary": {
    "dashboard": "tableau de bord",
    "deployment": "déploiement",
    "settings": "paramètres",
    "environment variable": "variable d'environnement",
    "webhook": "webhook",
    "API key": "clé API",
    "sign in": "se connecter",
    "sign out": "se déconnecter",
    "repository": "dépôt",
    "pull request": "demande de tirage"
  },
  "style_notes": "Formal technical French. Prefer native French terms over anglicisms where established equivalents exist. Keep UI labels concise — 3 words maximum where possible."
}

Ginagawa ng bawat field:

  • grammar_rules — Ini-inject sa LLM system prompt bilang mga tahasang constraint
  • dictionary — Itinutugma sa mga source key; kapag lumitaw ang isang termino sa dictionary, ini-inject ito bilang "required terminology" sa prompt
  • style_notes — Idinadagdag sa system prompt bilang pangkalahatang gabay sa estilo

Hakbang 3: I-configure ang Pair​

Sabihin sa champollion na gamitin ang llm-coached para sa French:

champollion.config.json
{
  "version": 3,
  "inputLocale": "en",
  "localesDir": "./locales",
  "pairs": {
    "en:fr": {
      "method": "llm-coached",
      "model": "google/gemini-3.5-flash",
      "temperature": 0.2
    }
  },
  "languages": {
    "fr": {
      "register": "Formal technical French (vous-form)",
      "name": "French"
    }
  }
}

Hakbang 4: Subukan Ito​

npx champollion sync --dry

Suriin ang dry-run output. Tiyaking:

  • ✅ Ginagamit nang magkakatugma ang mga termino sa dictionary ("tableau de bord," hindi "panneau de contrôle")
  • ✅ Ginagamit ang anyong vous sa kabuuan
  • ✅ Tumutugma ang mga teknikal na termino sa inyong dictionary

Pagkatapos, patakbuhin ang tunay na sync:

npx champollion sync

Hakbang 5: Mag-benchmark gamit ang Eval Harness (Opsyonal)​

Kung nais ninyo ng quality scores — at dapat po, dahil ang mga plugin ay ipinapadala kasama ng benchmark data — gamitin ang kasamang eval harness.

I-install ang Harness​

pip install mt-eval-harness

Gumawa ng Reference Corpus​

Gumawa ng file na may source strings at mga kinikilalang mahusay na pagsasalin:

corpus/french-formal.json
[
  {
    "source": "Dashboard",
    "reference": "Tableau de bord"
  },
  {
    "source": "Sign in to your account",
    "reference": "Connectez-vous à votre compte"
  },
  {
    "source": "Your deployment is ready",
    "reference": "Votre déploiement est prêt"
  },
  {
    "source": "Environment variables",
    "reference": "Variables d'environnement"
  }
]

Patakbuhin ang Benchmark​

mt-eval test \
  --corpus corpus/french-formal.json \
  --source en \
  --target fr \
  --model google/gemini-3.5-flash \
  --temperature 0.2 \
  --champollion-config champollion.config.json

Ang harness ay naglalabas ng:

  • chrF++ — Character-level F-score (0–100). Higit sa 70 ay malakas.
  • BLEU — N-gram overlap (0–100). Higit sa 40 ay matatag para sa coached translation.
  • Exact match rate — Proporsyon ng mga pagsasaling eksaktong tumutugma sa reference.
  • COMET — Neural quality metric (kung naka-install sa pamamagitan ng mt-eval setup --comet).

:::tip Subukan ang Ipinapadala Ninyo Ang paggamit ng --champollion-config ay direktang nag-i-import ng inyong production model, register, temperature, at coaching data mula sa inyong champollion.config.json. Tinitiyak nito na ang eksaktong paraang idi-deploy ninyo ang inyong bina-benchmark. :::

I-export ang Plugin​

Kapag kuntento na po kayo sa mga score:

mt-eval export \
  --name french-formal-v1 \
  --report eval/logs/harness/run_report.json \
  --output ./french-formal-v1/

Lumilikha ito ng:

french-formal-v1/
├── method.json          # Manifest with config + benchmarks
└── coaching/
    └── fr.json          # Your coaching data

Hakbang 6: I-install ang Plugin sa Champollion​

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

Kinokopya nito ang plugin sa .champollion/methods/french-formal-v1/.

I-update ang inyong config upang gamitin ito:

champollion.config.json
{
  "pairs": {
    "en:fr": {
      "methodPlugin": "french-formal-v1"
    }
  }
}

Hakbang 7: I-verify​

# Check plugin is installed and shows benchmark scores
npx champollion status

# Run a sync with the plugin
npx champollion sync

# Audit licensing status
npx champollion provenance

Ipapakita ng output na status ang:

en → fr
  Method:    french-formal-v1 (llm-coached)
  Model:     google/gemini-3.5-flash
  Quality:   high
  chrF++:    74.2
  BLEU:      46.8
  Exact:     42%

Ang Nabuo Ninyo​

Mayroon na kayo ngayon ng:

  1. Coaching data — Mga tuntunin sa gramatika at terminolohiya na nagpapatupad ng consistency
  2. Benchmark scores — Na-quantify na kalidad na ipinapadala kasama ng plugin
  3. Isang portable plugin — method.json + coaching data, na maaaring i-install sa anumang machine
  4. Production deployment — Naka-integrate sa inyong sync pipeline

Mga Susunod na Hakbang​