본문으로 건너뛰기

튜토리얼: 번역 플러그인 만들기

맞춤형 번역 방식을 처음부터 만들고, 벤치마크를 측정한 뒤, champollion 플러그인으로 배포해 보세요. 기성 API가 지원하지 않는 새로운 언어 쌍을 추가하는 전체 워크플로입니다.

만들게 될 것: 강제된 용어, 문법 규칙, 벤치마크 점수를 갖춘 격식 있는 프랑스어용 코칭 번역 플러그인입니다.

소요 시간: 30~45분

사전 준비물:

  • champollion 설치 (npm install --save-dev champollion)
  • OpenRouter API 키 (OPENROUTER_API_KEY)
  • Python 3.10+ (eval harness용)

1단계: 문제 파악하기​

SaaS 대시보드를 프랑스어로 번역하고 있다고 가정해요. 기본 llm 방식은 정확하지만 일관성이 없는 번역을 만들어냅니다:

  • 어떤 때는 "dashboard"가 "tableau de bord"로, 어떤 때는 "panneau de contrôle"로 번역돼요
  • 톤이 tu과 vous 형태 사이를 오갑니다
  • 기술 용어가 일관성 없이 영어화돼요

일반적인 LLM 프롬프트가 제공하지 않는 용어 강제와 격식 제어가 필요해요.

2단계: 코칭 데이터 만들기​

언어적 요구사항을 인코딩하는 코칭 파일을 만드세요:

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."
}

각 필드의 역할:

  • grammar_rules — 명시적 제약 조건으로 LLM 시스템 프롬프트에 주입돼요
  • dictionary — 소스 키와 매칭됩니다. 사전 용어가 나타나면 프롬프트에 "필수 용어"로 주입돼요
  • style_notes — 일반적인 스타일 지침으로 시스템 프롬프트에 추가돼요

3단계: 언어 쌍 구성하기​

champollion에게 프랑스어에 llm-coached을 사용하도록 지정하세요:

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"
    }
  }
}

4단계: 테스트하기​

npx champollion sync --dry

dry-run 출력을 검토하세요. 다음을 확인하세요:

  • ✅ 사전 용어가 일관되게 사용되었는지 ("panneau de contrôle"가 아닌 "tableau de bord")
  • ✅ vous 형태가 전체적으로 사용되었는지
  • ✅ 기술 용어가 사전과 일치하는지

그런 다음 실제 동기화를 실행하세요:

npx champollion sync

5단계: Eval Harness로 벤치마크하기 (선택)​

품질 점수가 필요하다면 — 그리고 플러그인은 벤치마크 데이터와 함께 배포되므로 필요할 거예요 — 함께 제공되는 eval harness를 사용하세요.

Harness 설치​

pip install mt-eval-harness

참조 코퍼스 만들기​

소스 문자열과 검증된 번역이 담긴 파일을 만드세요:

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"
  }
]

벤치마크 실행​

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

harness는 다음을 출력해요:

  • chrF++ — 문자 수준 F-점수 (0~100). 70 이상이면 우수합니다.
  • BLEU — N-gram 중첩도 (0~100). 코칭 번역의 경우 40 이상이면 견고합니다.
  • 정확 일치율 — 번역이 참조와 정확히 일치하는 비율이에요.
  • COMET — 신경망 품질 지표 (mt-eval setup --comet로 설치한 경우).

:::tip 배포할 것을 테스트하세요 --champollion-config을 사용하면 champollion.config.json에서 프로덕션 모델, 격식, 온도, 코칭 데이터를 직접 가져옵니다. 이를 통해 실제로 배포할 정확한 방식을 벤치마크하게 돼요. :::

플러그인 내보내기​

점수에 만족하면:

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

다음이 생성돼요:

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

6단계: Champollion에 플러그인 설치하기​

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

이렇게 하면 플러그인이 .champollion/methods/french-formal-v1/로 복사돼요.

이를 사용하도록 구성을 업데이트하세요:

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

7단계: 검증하기​

# 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

status 출력은 다음을 보여줘요:

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

만든 것​

이제 다음을 갖추게 되었어요:

  1. 코칭 데이터 — 일관성을 강제하는 문법 규칙과 용어
  2. 벤치마크 점수 — 플러그인과 함께 배포되는 정량화된 품질
  3. 이식 가능한 플러그인 — method.json + 코칭 데이터로, 어떤 머신에든 설치 가능해요
  4. 프로덕션 배포 — 동기화 파이프라인에 통합됨

다음 단계​