gemini-translate

Gemini Translate

使用 Gemini CLI 作为翻译子 Agent，批量翻译内容文件（Markdown、JSON、YAML frontmatter）。Claude 负责协调整个流程：识别缺失内容、结合术语表上下文构建提示词、通过一次 CLI 调用分派给 Gemini、验证输出结构并写入文件。

为什么使用 Gemini CLI

• 通过 OAuth 使用 Google AI Ultra 套餐（无需 API 密钥）
• 100 万 token 上下文，一次调用即可容纳完整术语表和数十个源文件
• 只需一次启动成本（约 13 秒），无需承担逐个文件的开销
• 由 Claude 掌控协调、验证和文件写入

先决条件

• 已安装并完成身份验证的 Gemini CLI（gemini 在 PATH 中，已配置 OAuth）
• 结构一致的源内容文件（带 frontmatter 的 Markdown、JSON 等）

流程概览

Claude: find translation gaps (missing .es.* files, parity tests)
  |
Claude: read source files + glossary + existing translations for tone
  |
Claude: build batch prompt and call gemini-translate.sh
  |
Gemini: translate all files in one shot, return JSON
  |
Claude: parse response, validate structure, write .es.* files
  |
Claude: run project tests (i18n symmetry, coverage)

用法

步骤 1：识别缺失内容

查找缺少对应语言版本的内容文件：

# Generic pattern -- adjust paths and extensions for your project
for f in content/**/*.md; do
  base=$(basename "$f")
  [[ "$base" == *.es.* ]] && continue
  name="${base%.*}"
  dir=$(dirname "$f")
  [ ! -f "$dir/${name}.es.md" ] && echo "MISSING: $f"
done

如果项目中有 i18n 一致性测试，也可以运行这些测试。

步骤 2：准备术语表

创建术语表，确保术语翻译一致。术语表是嵌入提示词中的简单文本块：

## Glossary (EN -> ES)
- "OB/GYN Physician" -> "Medico OB/GYN"
- "High-risk pregnancy" -> "Embarazo de alto riesgo"
- "Certified Nurse Midwife" -> "Enfermera Partera Certificada"

如果项目已有术语表（Python 字典、CSV、JSON），请在运行脚本前将其转换为此格式。脚本可通过 --glossary 接收术语表文件。

步骤 3：运行批量翻译

bash gemini-translate.sh \
  --source-lang en \
  --target-lang es \
  --glossary glossary.txt \
  --model gemini-2.5-pro \
  --instructions "Use formal 'usted'. Latin American Spanish, not Spain. Warm but professional tone for patient-facing medical content." \
  file1.md file2.md file3.md

脚本会：

1. 读取所有源文件
2. 将术语表、说明和所有文件内容合并为一个提示词
3. 调用 gemini -p "..." -o json --approval-mode plan
4. 解析 JSON 响应，并将每个译文作为 JSON 数组打印到 stdout

步骤 4：由 Claude 验证并写入

脚本返回后，Claude 应执行以下操作：

1. 解析 JSON 输出
2. 对每个译文文件：
   • 验证 frontmatter 键与源文件完全一致
   • 验证链接、图片路径和品牌名称均已保留
   • 验证 Gemini 未添加任何 `` 标记（或将其告知用户）
3. 写入 .es.* 文件
4. 运行项目的 i18n 测试

脚本参考

gemini-translate.sh

Usage: gemini-translate.sh [OPTIONS] FILE [FILE...]

Options:
  --source-lang LANG    Source language code (default: en)
  --target-lang LANG    Target language code (default: es)
  --glossary FILE       Path to glossary file (term mappings, one per line)
  --instructions TEXT   Additional translation instructions for tone/style
  --model MODEL         Gemini model override (default: system default)
  --max-tokens N        Max estimated input tokens per batch (default: 80000)
  --gemini-bin PATH     Path to gemini binary (bypasses wrapper detection)
  --dry-run             Print the prompt without calling Gemini

Output: JSON array to stdout
  [
    {"file": "about.md", "translation": "---\ntitle: Acerca de\n---\n..."},
    {"file": "careers.md", "translation": "---\ntitle: Carreras\n---\n..."}
  ]

Exit codes:
  0  Success
  1  Gemini CLI not found or not authenticated
  2  No input files provided
  3  Gemini returned an error or unparseable output

翻译质量规则

以下规则会嵌入发送给 Gemini 的提示词中：

1. 严格保留结构：frontmatter 键、Markdown 格式、链接、HTML 标签和图片路径
2. 绝不翻译：品牌名称、专有名词、URL、文件路径、凭据（MD、DO、CNM 等）
3. 医学术语：使用术语表。遇到术语表中未收录且不确定的术语时，用 `` 将其括起来
4. 语气：与源文档的语气保持一致。面向患者的医学内容应温暖、令人安心且专业
5. 输出格式：返回完整的译文文件内容（frontmatter + 正文），而非仅返回修改部分

适配其他项目

此技能与具体项目无关。要在新的代码库中使用：

1. 文件约定：设置项目的语言版本文件命名模式（.es.md、.es.json、locales/es/ 等）
2. 术语表：将领域专用术语整理到术语表文件中
3. 说明：为目标语言编写一段风格指南
4. 验证：指定 Claude 使用项目的 i18n 测试，或编写简单的键值对比检查

Gemini CLI 包装器兼容性

许多用户使用会默认添加 --yolo/-y 的 shell 包装器（例如 ~/bin/gemini）。这与 --approval-mode 冲突。脚本通过以下方式避免此问题：

1. 优先使用 pnpx @google/gemini-cli（直接调用程序包，不经过包装器）
2. 仅在 pnpx 不可用时，才回退到 PATH 中的 gemini
3. 接受 --gemini-bin /path/to/binary 参数，以完全覆盖自动检测结果

脚本使用 -o json 获取结构化输出，该输出会返回 {session_id, response, stats} 信封。内嵌的 Python 解析器会提取 response 字段，并自动处理 Markdown 代码围栏、空字节和 MCP 警告前缀。

基于令牌的批处理

脚本不会按固定文件数处理，而是估算输入令牌数（1 个令牌约等于 4 个字符），达到预算后便停止添加文件。默认的 --max-tokens 80000 会为翻译输出留出空间（EN->ES 的输出大约是输入的 1.2 倍）。超过预算的文件会列为跳过，以便调用方运行后续批次。

截断恢复

当 Gemini 达到输出令牌上限并在 JSON 条目中途截断时，脚本会通过以下方式恢复：

1. 检测不完整的 JSON
2. 从末尾逐步截短，以查找有效的 JSON 边界
3. 丢弃最后一个（很可能已被截断的）条目
4. 报告恢复了多少条完整翻译

Agentic 工作流与氛围编程

• 迭代翻译： 不要期望首次批处理就能实现完美的语言风格或结构保留。先起草一个小型测试批次，检查输出的语气和格式，找出任何重复出现的翻译错误，每次只调整一个变量来优化术语表或提示词说明，并在处理整个项目之前重新运行测试。
• 氛围编程： 运行翻译批次前，先在本地提交工作中的源内容和术语表更新；再单独提交生成的 .es.* 文件，以便在模型虚构了结构时轻松回退。

限制

• 每次调用仅支持一种语言对：脚本一次处理一个源语言/目标语言语言对。对于多语言项目，请针对每种目标语言分别运行一次。
• Gemini CLI 启动耗时：每次批次调用约有 13 秒的开销。批处理可以分摊这部分开销。
• 输出令牌上限：默认预算为 80K 个输入令牌。如果发生截断，请降低 --max-tokens。
• 不支持流式传输：脚本会等待完整响应。大型批次除了启动时间外，模型处理可能还需要 30–60 秒。
• 需要 Python 3：JSON 提取使用了内嵌的 Python 脚本。