메인 콘텐츠로 건너뛰기

튜토리얼: Translation Plugin 만들기

처음부터 커스텀 translation method를 만들고, 벤치마크를 수행한 뒤, rosetta 플러그인으로 배포해 보세요. 기성 API가 지원하지 않는 새로운 언어 쌍을 추가하는 전체 워크플로우예요.

만들게 될 결과물: 용어, 문법 규칙, 벤치마크 점수가 적용된 격식 있는 프랑스어용 coached translation 플러그인이에요.

소요 시간: 30–45분

사전 준비 사항:

  • i18n-rosetta 설치 (npm install --save-dev i18n-rosetta)
  • OpenRouter API 키 (OPENROUTER_API_KEY)
  • Python 3.10 이상 (eval harness용)

1단계: 문제 파악하기​

SaaS 대시보드를 프랑스어로 번역하려고 해요. 기본 llm method는 정확하지만 일관성 없는 번역을 생성해요:

  • "dashboard"가 어떨 때는 "tableau de bord"로, 어떨 때는 "panneau de contrôle"로 번역돼요.
  • 어조가 tu 형태와 vous 형태를 오가요.
  • 기술 용어가 일관성 없이 영어식으로 표현돼요.

일반적인 LLM 프롬프트에서는 제공하지 않는 용어 강제 적용과 어조 제어가 필요해요.

2단계: Coaching Data 만들기​

언어적 요구 사항을 인코딩하는 coaching 파일을 만들어 보세요:

mkdir -p .rosetta/coaching
.rosetta/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단계: Pair 구성하기​

프랑스어에 llm-coached를 사용하도록 rosetta에 설정해 주세요:

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

4단계: 테스트하기​

npx i18n-rosetta sync --dry

dry-run 출력을 검토해 보세요. 다음 사항을 확인해 주세요:

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

그런 다음 실제 동기화(sync)를 실행해요:

npx i18n-rosetta sync

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

품질 점수를 원한다면 보조 도구인 eval harness를 사용해 보세요. 플러그인은 벤치마크 데이터와 함께 제공되므로 이 과정이 필요할 거예요.

Harness 설치하기​

git clone https://github.com/gamedaysuits/gds-mt-eval-harness.git
cd gds-mt-eval-harness
pip install -r requirements.txt

Reference Corpus 만들기​

소스 문자열과 검증된 번역이 포함된 파일을 만들어 보세요:

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

벤치마크 실행하기​

python harness.py eval \
  --corpus corpus/french-formal.json \
  --source en \
  --target fr \
  --method llm-coached \
  --model google/gemini-3.5-flash

harness의 출력 결과는 다음과 같아요:

  • chrF++ — 문자 수준의 F-score(0–100)예요. 70 이상이면 우수한 수준이에요.
  • BLEU — N-gram 중복도(0–100)예요. 40 이상이면 coached translation으로서 탄탄한 수준이에요.
  • Exact match rate — 레퍼런스와 정확히 일치하는 번역의 비율이에요.

플러그인 내보내기​

점수에 만족한다면 다음을 실행해 주세요:

python harness.py export \
  --name french-formal-v1 \
  --output ./french-formal-v1/

그러면 다음 파일이 생성돼요:

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

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

npx i18n-rosetta plugin install ./french-formal-v1/

플러그인이 .rosetta/methods/french-formal-v1/에 복사돼요.

이를 사용하도록 config를 업데이트해 주세요:

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

7단계: 확인하기​

# Check plugin is installed and shows benchmark scores
npx i18n-rosetta status

# Run a sync with the plugin
npx i18n-rosetta sync

# Audit licensing status
npx i18n-rosetta 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. Coaching data — 일관성을 강제하는 문법 규칙과 용어
  2. Benchmark scores — 플러그인과 함께 제공되는 정량화된 품질 점수
  3. 이식 가능한 플러그인 — 모든 기기에 설치할 수 있는 method.json + coaching data
  4. 프로덕션 배포 — 동기화(sync) 파이프라인에 통합됨

다음 단계​