메서드 플러그인 사양

버전: 1.1
대상: 플러그인 개발자
표준 스키마: schemas/rosetta-plugin.schema.json

개요

i18n-rosetta는 플러그형 메서드 시스템을 사용해요. 각 언어 쌍은 서로 다른 번역 메서드(LLM, coached, script-converter 등)를 사용할 수 있어요. 메서드는 lib/translate.js에 등록되며 lib/pairs.js을 통해 쌍별로 확인돼요.

eval harness의 역할은 번역 메서드를 개발, 테스트 및 내보내기하는 것이에요. i18n-rosetta의 역할은 이를 소비하고 실행하는 것이에요. harness는 rosetta 내부에서 실행되지 않아요.

데이터 흐름

---

메서드 플러그인 형식

메서드 플러그인은 단일 JSON 파일(method.json)과 선택적인 코칭 데이터 파일로 구성돼요.

method.json — 필수

{
  "name": "french-formal-v1",
  "type": "llm-coached",
  "version": "1.0.0",
  "description": "Formally-tuned French with terminology enforcement and grammar coaching",
  "author": "Plugin Author",

  "config": {
    "model": "google/gemini-3.5-flash",
    "register": "formal",
    "batchSize": 30,
    "temperature": 0.2
  },

  "locales": ["fr"],

  "benchmarks": {
    "fr": {
      "date": "2026-05-11T00:00:00Z",
      "corpus_size": 500,
      "exact_match_rate": 0.42,
      "corpus_chrf": 72.3,
      "corpus_bleu": 45.1,
      "model": "google/gemini-3.5-flash",
      "harness_version": "1.0.0"
    }
  },

  "provenance": {
    "resources": [],
    "commercialReady": false,
    "flags": ["license-unclear"]
  },

  "coaching": {
    "dir": "coaching"
  }
}

필드 참조

필드	유형	필수 여부	설명
name	string	✅	고유 메서드 식별자(kebab-case)
type	string	✅	Rosetta 메서드 유형: llm, llm-coached, api, google-translate, deepl, microsoft-translator, libretranslate, openai, anthropic, gemini
version	string	✅	Semver 버전(예: 1.0.0)
locales	string[]	✅	이 메서드가 대상으로 하는 로캘 코드(최소 1개)
description	string	—	사람이 읽을 수 있는 설명
author	string	—	이 메서드를 개발/테스트한 사람
config.model	string	—	OpenRouter 모델 식별자
config.register	string	—	대상 언어의 어조/말투(register/tone)
config.batchSize	number	—	API 배치당 키 수(1–200, 기본값: 30)
config.temperature	number	—	LLM temperature(0.0–2.0, 기본값: 0.3)
benchmarks	object	—	로캘별 벤치마크 결과
provenance	object	—	라이선스 및 리소스 종속성
coaching.dir	string	—	코칭 데이터 디렉터리의 상대 경로

Benchmark 객체(로캘별)

필드	유형	필수 여부	설명
date	string	✅	벤치마크 실행의 ISO 8601 타임스탬프
corpus_size	number	✅	평가된 항목 수
exact_match_rate	number	✅	0.0–1.0, 정확히 일치하는(exact match) 비율
corpus_chrf	number	—	chrF++ 점수(0–100)
corpus_bleu	number	—	BLEU 점수(0–100)
model	string	✅	평가(eval) 중에 사용된 모델
harness_version	string	✅	사용된 evaluation harness의 버전

:::info 어떤 지표가 표시되나요? rosetta status 명령은 benchmark 블록의 chrF++ 및 **정확도(exact match rate)**를 표시해요. corpus_bleu는 매니페스트에서 허용되지만, 현재 rosetta 명령에서 표시되거나 사용되지 않아요. 메서드 리더보드는 chrF++, 정확도 및 FST 승인율을 추적해요. :::

---

Provenance 객체

provenance 블록은 플러그인에 번들로 제공되는 리소스의 라이선스 상태를 전달해요.

필드	유형	기본값	설명
resources	object[]	[]	name, license 및 type이 포함된 번들 리소스 목록
commercialReady	boolean	false	플러그인이 상업적 배포를 위해 승인되었는지 여부
flags	string[]	["license-unclear"]	기계가 읽을 수 있는 상태 플래그

기본 상태 — 내보낸 플러그인은 commercialReady: false 및 flags: ["license-unclear"]과 함께 제공돼요.

승인된 상태 — 라이선스가 확인된 경우: commercialReady: true을 설정하고 플래그를 지워요.

---

코칭 데이터 형식

type가 llm-coached인 경우, 플러그인은 coaching/ 하위 디렉터리에 코칭 데이터 파일을 포함해야 해요.

coaching/<locale>.json

{
  "grammar_rules": [
    "French adjectives agree in gender and number with the noun they modify",
    "Use 'vous' for formal contexts, 'tu' for informal"
  ],
  "dictionary": {
    "dashboard": "tableau de bord",
    "deployment": "déploiement",
    "settings": "paramètres"
  },
  "style_notes": "Prefer active voice. Avoid anglicisms where a native French term exists."
}

필드	유형	필수 여부	설명
grammar_rules	string[]	—	이 로캘의 모든 LLM 프롬프트에 주입되는 규칙
dictionary	object	—	용어 → 번역 맵. 일치하는 용어는 필수 용어로 주입돼요.
style_notes	string	—	프롬프트에 추가되는 자유 형식의 스타일 지침

---

디렉터리 구조

french-formal-v1/
  method.json                 # Method manifest with benchmarks
  coaching/
    fr.json                   # Coaching data for French

다중 로캘 메서드의 경우:

european-formal-v2/
  method.json                 # locales: ["fr", "de", "es", "it"]
  coaching/
    fr.json
    de.json
    es.json
    it.json

---

Rosetta가 플러그인을 소비하는 방법

설치

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

.rosetta/methods/french-formal-v1/에 저장돼요.

구성

i18n-rosetta.config.json

{
  "pairs": {
    "en:fr": {
      "methodPlugin": "french-formal-v1"
    }
  }
}

:::info 병합 의미론(Merge semantics) 플러그인은 어떤 메서드를 사용할지(type)를 정의해요. 쌍(pair) 구성은 이를 어떻게 실행할지(model, register, batchSize)를 조정해요. 쌍에서 model을 설정하면, 플러그인의 기본값을 재정의해요. :::

런타임

1. Rosetta는 .rosetta/methods/french-formal-v1/에서 method.json을 읽어요.
2. 플러그인의 type 필드가 번역 메서드(예: llm-coached)를 설정해요.
3. 플러그인의 coaching/ 디렉터리에서 코칭 데이터를 로드해요.
4. config 블록을 사용하여 모델/어조/temperature의 빈 부분을 채워요.
5. benchmarks 블록은 rosetta status 출력에 표시돼요.
6. rosetta provenance이 provenance 블록에서 라이선스 플래그를 확인해요.

---

스키마 유효성 검사

플러그인 매니페스트는 설치 시 schemas/rosetta-plugin.schema.json에 대해 유효성 검사를 거쳐요.

IDE 자동 완성을 위해 method.json에서 스키마를 참조하세요:

{
  "$schema": "./node_modules/i18n-rosetta/schemas/rosetta-plugin.schema.json",
  "name": "my-method-v1"
}

---

포함하지 말아야 할 항목

• ❌ Python 코드 또는 harness 종속성
• ❌ 원시 말뭉치 데이터 또는 실행 로그
• ❌ API 키 또는 자격 증명
• ❌ harness 구성
• ❌ 내부 프롬프트 템플릿(rosetta의 메서드 구현에 존재함)

플러그인은 구성, 코칭 콘텐츠 및 벤치마크 결과와 같은 데이터 전용이에요.

---

참고 항목

• 번역 메서드 — 각 내장 메서드의 작동 방식
• 구성 — 쌍별 및 언어별 구성
• API를 통해 메서드 제공하기 — 메서드를 HTTP 서비스로 호스팅하기
• 쿡북: FST-Gated 파이프라인 — 파이프라인 구축 및 패키징
• MT 평가 — 리더보드 제출을 위한 메서드 벤치마킹
• 리소스가 부족한 언어 지원 — 커뮤니티 플러그인의 사용 사례