blog-translate

博客翻译：SEO 优化的博客翻译

以下捆绑路径使用宿主 Markdown 对 ${CLAUDE_SKILL_DIR} 进行替换； 它不是导出的 shell 变量。执行前请解析这些路径、对路径加引号， 并拒绝非绝对路径的覆盖值。将从 ${CLAUDE_SKILL_DIR}/../blog/references 解析出的 blog_reference_root、从 ${CLAUDE_SKILL_DIR}/../blog/templates 解析出的 blog_template_root，以及所需的同级根目录传递给 Agent。 加载项目上下文之前，先阅读主参考文档 orchestration-details.md； 只向下游 Agent 传递其由 helper 标记的输出。

将现有博客文章翻译成一种或多种目标语言。与通用翻译不同， 此技能会生成针对 SEO 优化、可直接发布的内容，包含本地化关键词、元标签和符合文化习惯的格式。

改编自 Chris Mueller 的 claude-blog-multilingual（Pro Hub Challenge， 2026 年 3 月）。原始仓库自 2026-10-12 起已不可用

关键参考资料

按需加载：

• ${CLAUDE_SKILL_DIR}/references/translation-rules.md：格式保留，以及各地区的数字／日期／货币 格式、引号处理和质量标准。
• ${CLAUDE_SKILL_DIR}/references/cultural-adaptation.md：各地区的文化特征（DACH、 法语区、西语区、日本、自定义）。此文件与 blog-localize 共用（请勿重复）。

工作流

阶段 1：解析输入

1. 仅在将源文件路径解析为相对于项目根目录／当前工作目录后，才读取源文件（Markdown、MDX 或 HTML）。 拒绝符号链接路径、指向根目录之外的路径、超过 10 MB 的文件以及二进制文件。
2. 自动检测源语言。优先顺序：
   • Frontmatter 中的 lang 字段。
   • HTML 的 lang 属性。
   • 内容分析（文字体系、常见虚词）。
3. 将 --to 中的目标语言解析为以逗号分隔、兼容 Google hreflang 的标签 （de、fr、es-MX、ja、pt-BR、zh-Hant）。 如果缺少 --to，只询问用户一次：“要翻译成哪些语言？ 请提供 hreflang 标签，例如 de、fr、es-MX、ja、pt-BR。”
4. 使用 blog-multilingual、blog-localize 和 blog-locale-audit 共用的多语言地区规则规范化每个代码： ISO 639-1 语言代码使用小写，可选的 ISO 15924 文字体系代码使用首字母大写，可选的 ISO 3166-1 Alpha-2 地区代码使用大写。无效代码应拒绝并提供建议（jp 会提示“您是不是指日语的 ja？”）。对于 es、pt 和 zh 等存在歧义的仅语言目标，必须指定地区或明确选择中性模式。Google 接受单独的语言代码作为 hreflang（https://developers.google.com/search/docs/specialty/international/localized-versions， 于 2026-10-12 阅读），但不接受单独的地区代码；这项更严格的规则是为了保证翻译质量，并非 Google 要求指定地区。如果目标语言与规范化后的源语言相同，则跳过该目标并告知用户。

阶段 2：内容分析

提取可翻译内容：

• Frontmatter：title、description、tags、author（仅当可翻译时，例如角色标签，不包括个人姓名）。
• 所有标题（H1、H2、H3）。
• 正文段落。
• 图片的 alt 文本和 <figcaption> 内容。
• 图表中的 <text> 和 <tspan> 内容；保留所有 SVG 属性（x、 y、font-size、fill、transform）。
• FAQ 问题和答案。
• 有证据支持的说明文字。
• Key Takeaways 或摘要框。
• CTA 文本。
• 内部链接区域的锚文本。

保持不变：

• Markdown 和 HTML 结构、标签、属性。
• 图片 URL、链接 URL、frontmatter 键。
• 可执行代码围栏和行内代码。仅翻译可执行代码外的注释，或在用户明确要求本地化教程注释时翻译。
• 内部链接区域标记（[INTERNAL-LINK: ...]）。
• 引用中的来源组织名称（Gartner、McKinsey 等）。
• 人名。
• Schema JSON-LD 块（仅翻译面向用户的内容字符串；绝不翻译 Person、Organization 或 Brand 名称、URL、ID、@id 或 sameAs）。

确定阶段 3 的主要关键词和次要关键词。

阶段 3：关键词本地化

针对每种目标语言：

1. 判断源关键词是否为目标市场中通用的术语。如果是（例如，“Content Marketing”在德语中保持不变），则保留。
2. 如果本地化对应词确实有搜索行为，则替换为该词。
3. 对次要关键词采用相同逻辑。
4. 记录映射关系。翻译 Agent 会据此统一更新标题、元描述和 H2 标题。

阶段 4：翻译

针对每种目标语言，通过 Task 启动 blog-translator Agent，并提供：

• 源内容。
• 阶段 3 的关键词本地化映射。
• 目标语言代码。
• ${CLAUDE_SKILL_DIR}/references/translation-rules.md 的路径。
• 指示其将本阶段限制在语言、语体、自然的主题覆盖和格式方面。品牌、法律、统计数据和文化替换留给 blog-localize 处理。

翻译为多种语言时，并行运行各 Agent。

当 blog-multilingual 调用此技能时，其调用以 Mode: orchestrated 开始；请参阅阶段 5（输出根目录）和阶段 7（约定）。

Agent 会以与输入相同的格式返回完整译文。

阶段 5：后处理

针对每个译文版本：

1. 添加或更新地区 frontmatter：

   lang: "de"
   translatedFrom: "en"
   translatedDate: "YYYY-MM-DD"
   slug: "wie-man-ki-slop-vermeidet"
   

2. 验证结构完整性：

   • H2 和 H3 的数量与原文相同。
   • 所有图片均保留，并带有已翻译的 alt 文本。
   • 所有 SVG 图表均保留，并带有已翻译的文本标签（根据长度调整：DE +30%、FR +15%、JA -20%；其他语言请参阅 ${CLAUDE_SKILL_DIR}/references/translation-rules.md）。
   • FAQ 数量相同。
   • 原文中存在的有证据支持的说明内容均保持完整。

3. 保存译文文件。每次运行只能采用一个输出根目录：

   • 独立运行（/blog translate）：当前工作目录下的 translations/{lang}/{localized-slug}.{ext}。
   • 编排运行（调用以 Mode: orchestrated 开始）：multilingual/{lang}/{localized-slug}.{ext}，即编排器创建的目录。绝不可同时写入 translations/。

   写入前，将 {localized-slug} 转换为仅含小写 ASCII 字母、数字和连字符的 slug；拒绝空值或保留名称。仅根据规范化后的 hreflang 代码创建语言目录。解析最终路径，并确保其位于预期输出根目录内；拒绝符号链接形式的输出路径。

第 6 阶段：翻译质量保障

完成前，检查输出中是否存在机器翻译痕迹：

• 直译的习语（照搬英语习语，而非采用恰当的表达）。
• 语序不自然（将 SOV 语序翻译成非 SOV 语言的 SVO 语序，或反之）。
• 句子中混用语言（公认的外来词除外）。
• 数字、日期或货币字符串仍沿用源格式。
• 前置元数据字符串仍使用源语言。

在每处问题旁标注文件路径、行号和修改建议。翻译 Agent 应在交付前重新处理所有标注的段落。

第 7 阶段：最终交付约定

翻译可能会更改内容主张、链接、元数据、架构和渲染布局。

编排模式。 由 blog-multilingual 调用时（编排模式），跳过交付约定；blog-multilingual 会在最终文本上按语言执行一次。调用内容顶部出现字面行 Mode: orchestrated 即表示编排模式。 在此模式下，将每种语言的状态报告为 pending (contract deferred to blog-multilingual)，且绝不可称翻译已完成或可发布。

独立运行。 在称任何翻译文件已完成或可发布之前，针对每种最终语言独立执行以下标准流程（此技能是该语言的最后一次文本更改）：

1. 解析 BLOG_SCRIPT_DIR="${CLAUDE_BLOG_SCRIPTS_DIR:-${CLAUDE_SKILL_DIR}/../../scripts}" 并确认其为绝对路径。绝不可从当前项目的 scripts/ 目录解析辅助程序。
2. 视觉素材：在目标语言输出目录下创建每种语言专用的交付暂存目录，并使用小写的本地化 slug 将最终语言文件复制到其中。处理所有草稿标记（[INTERNAL-LINK、[IMAGE、[CHART）：不得残留任何标记。沿用源文件的主视觉图（复制为 hero.<ext>）；新增付费主视觉图须通过 blog-image 成本和授权门槛。
3. 渲染：python3 "$BLOG_SCRIPT_DIR/blog_render.py" --md <locale-file> --out-dir <locale-delivery-dir>。
4. 初始化 nonce：python3 "$BLOG_SCRIPT_DIR/blog_preflight.py" --draft <locale-delivery-dir> --init-review-nonce。
5. 审核：仅将打印出的 nonce 传给新的 blog-reviewer 调用，以审核渲染后的语言版本 HTML。审核者会返回文本；将其原样保存到 <locale-delivery-dir>/review.md。
6. 门槛检查：python3 "$BLOG_SCRIPT_DIR/blog_preflight.py" --draft <locale-delivery-dir> --strict --slug <localized-slug>。
7. 循环：文件、主视觉图、HTML 或 PDF 发生任何更改后，都要重新渲染、重新初始化 nonce 并重新审核。最多迭代 3 次。

必须达到 90+/100、P0 为零、nonce 匹配、最终结果为 BLOCKING: false，并通过所有其他门槛。未通过的语言版本仍为 draft-blocked；报告其诊断信息，且不要称其已完成。

第 8 阶段：交付

## Translation complete: [Original title]

### Source
- Language: [source]
- File: [source path]

### Translations
| Language | File | Keywords adapted | Status |
|----------|------|------------------|--------|
| de | translations/de/{slug}.md | [N] | passed / draft-blocked / pending (orchestrated) |
| fr | translations/fr/{slug}.md | [N] | passed / draft-blocked / pending (orchestrated) |

### Quality checks
- Structural integrity: pass / fail per language
- Meta tags localized: pass / fail per language
- Numbers, dates, currencies formatted per locale: pass / fail
- Keywords localized: [N] keywords adapted
- Machine-translation artifacts flagged: [N] (see notes above)
- Delivery contract: score, P0 status, nonce verification, and preflight report per locale (standalone only; deferred to blog-multilingual in orchestrated mode)

### Next steps
- Run `/blog localize <file> --locale <code>` for cultural deep-adaptation.
- Run `/blog locale-audit translations/` to verify completeness.
- Use `/blog multilingual` to combine write, translate, localize, hreflang
  in one command.

错误处理

情况	操作
不支持的语言代码	建议使用正确的、兼容 Google 的 hreflang 代码
源语言与目标语言相同	跳过，并显示“源内容已是 [lang]”
未找到文件	报告错误并提供建议路径
翻译 Agent 超时	重试一次，然后报告部分结果
二进制文件或非文本文件	报告错误，并建议提供正确的文件

交叉引用

• 下一步（深入本地化）：/blog localize <file> --locale <code>
• 扫描所有语言版本的质量：/blog locale-audit <directory>
• 一键处理流程：/blog multilingual <topic> --languages <codes>