教程：构建翻译插件
从零开始构建自定义翻译方法，对其进行基准测试，并将其部署为 rosetta 插件。这是添加现成 API 不支持的新语言对的完整工作流程。
你将构建的内容： 一个针对正式法语的辅导式翻译插件，包含强制术语、语法规则和基准测试分数。
时间： 30–45 分钟
先决条件：
- 已安装 i18n-rosetta (
npm install --save-dev i18n-rosetta) - OpenRouter API 密钥 (
OPENROUTER_API_KEY) - Python 3.10+（用于 eval harness）
第一步：确认问题
你正在将一个 SaaS dashboard 翻译成法语。默认的 llm 方法生成的翻译虽然正确，但不一致：
- 有时 "dashboard" 被翻译成 "tableau de bord"，有时又变成 "panneau de contrôle"
- 语气在
tu和vous形式之间交替 - 专业术语的英语化处理不一致
你需要通用 LLM 提示词无法提供的术语强制执行和语域控制。
第二步：创建辅导数据
创建一个包含你语言要求的辅导文件：
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— 附加到系统提示词中，作为一般风格指南
第三步：配置语言对
告诉 rosetta 对法语使用 llm-coached：
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"
}
}
}
第四步：进行测试
npx i18n-rosetta sync --dry
查看 dry-run 输出。检查是否：
- ✅ 字典术语使用一致（是 "tableau de bord"，而不是 "panneau de contrôle"）
- ✅ 全程使用
vous形式 - ✅ 专业术语与你的字典匹配
然后运行真正的同步：
npx i18n-rosetta sync
第五步：使用 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
创建参考语料库
创建一个包含源字符串和已知优质翻译的文件：
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 算是不错的结果。
- 完全匹配率 — 与参考翻译完全匹配的翻译比例。
导出插件
一旦你对分数感到满意：
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
第六步：在 Rosetta 中安装插件
npx i18n-rosetta plugin install ./french-formal-v1/
这会将插件复制到 .rosetta/methods/french-formal-v1/。
更新你的配置以使用它：
i18n-rosetta.config.json
{
"pairs": {
"en:fr": {
"methodPlugin": "french-formal-v1"
}
}
}
第七步：验证
# 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%
你构建了什么
你现在拥有了：
- 辅导数据 — 强制保持一致性的语法规则和术语
- 基准测试分数 — 随插件附带的量化质量指标
- 便携式插件 —
method.json+ 辅导数据，可安装在任何机器上 - 生产部署 — 已集成到你的同步管道中