| name | html-i18n |
| description | 纯静态 HTML 站点翻译 —— 只处理 .html/.css/图片构成的纯静态站点（书籍、文档站、博客、官网落地页），生成各语言独立 HTML 目录（en/、ja/ 等），不引入 JS、不改源码逻辑。判定信号：项目目录里只有 .html/.htm/.css + 图片资源，没有 .jsx/.ts/.tsx/.vue/.py/.php/.java 源码、没有 package.json/composer.json/框架文件。⚠️ 若项目是编程框架源码（React/Vue/Laravel/WordPress 等，需要在代码里写 t()/__() 翻译函数），改用 i18n-helper，本 skill 不适用。 |
🌐 html-i18n — 静态 HTML 站点多语言助手
专注静态多页 HTML 站点的国际化翻译：书籍、文档站、博客、官网落地页等。
采用「目录/路由方案」—— 每种语言一个独立目录，纯静态、SEO 友好、零 JS 依赖。
与 i18n-helper（面向 React/Vue/Laravel 等编程框架源码、依赖 t()/__() 函数）互补不重叠。
该用哪个翻译 skill？（先判定再动手）
按项目目录里的文件类型判定，不要只看用户怎么措辞：
| 看到什么 | 用哪个 skill |
|---|
只有 .html/.htm + .css + 图片，无源码 | ✅ html-i18n（本 skill） |
有 package.json/composer.json + .js/.jsx/.vue/.php 等源码 | ❌ 改用 i18n-helper |
| React/Vue/Angular/Laravel/Symfony/WordPress 项目 | ❌ 改用 i18n-helper |
用户说「在代码里加 t()/__() 翻译函数」 | ❌ 改用 i18n-helper |
本质区别：本 skill 是「复制 HTML 并替换文本」产出静态目录；i18n-helper 是「改源码逻辑」产出翻译函数调用 + 语言配置文件。
触发条件
当用户要求以下任一操作，且目标是纯静态 HTML 站点时激活：
- 翻译一个 HTML 网站 / 静态网页站点
- 给这个网站/文档站做国际化、多语言
- 把这套 HTML 书翻成英文/日文/繁中等
- 生成网页的多语言版本（en/、ja/ 等语言目录）
若项目是 React/Vue/Angular 等前端框架（含 .jsx/.tsx/.vue、用 t() 函数），
或 PHP/Laravel/WordPress 等，改用 i18n-helper。本 skill 只处理纯静态 HTML（可含内联 CSS，但不应有构建框架）。
工作流程（五步）
翻译一个静态 HTML 站点，按此顺序执行：
- 分析项目结构 —— 定位 HTML 根目录、确认是纯静态站（无框架）
- 提取翻译源 —— 运行
extract.py 生成 locales/zh-CN.json
- 翻译 —— 基于 zh-CN.json 产出各语言 json（本步由你 LLM 完成，见下「翻译规范」）
- 应用生成 —— 运行
apply.py 把译文回填，生成 en/、ja/ 等语言目录
- 完整性检查 —— 运行
check.py 验证完成度，抽检关键页面
所有脚本在 scripts/ 下，仅依赖 Python 标准库（无需 pip 安装）。
第 1 步：分析项目结构
- 确认目标目录是纯静态 HTML（
.html + .css + 图片），无 package.json/框架文件
- 统计 HTML 文件数、识别共享资源（css、图片目录）
- 识别源语言（看
<html lang="..."> 或正文，通常是 zh-CN）
- 问清目标语言（如 en-US、ja-JP、zh-TW）—— 这是必填项
第 2 步：提取翻译源
python scripts/extract.py <html根目录>
生成 <根目录>/locales/ 三件套：
zh-CN.json —— 翻译源：key -> 原文。翻译时复制此文件改名（如 en-US.json）并替换值为译文。_index.json —— key 的元信息（文件/标签/属性），apply 定位用，不要手改。_common.json —— 跨文件重复文本（导航词等）已归并为 common.* key，保证全站一致。
默认源语言代码取 zh-CN。若站点源语言不是中文，用 --out 指定输出目录后，
把生成的 json 文件名改成你的源语言代码（如 en.json），翻译目标语言另存。
第 3 步：翻译（LLM 执行）
复制 zh-CN.json 为各目标语言文件（en-US.json、ja-JP.json、zh-TW.json），
保持 key 不变，只替换 value 为译文。必须遵守：
翻译规范（强制）
绝不翻译这些（脚本已自动跳过，但翻译时也要注意）
- URL、
href/src 路径、CSS class/id、lang 属性值
<pre><code> 代码块（SQL/命令/配置）—— 默认整块保留- 技术术语（见 glossary）：产品名、缩写词（如 API、SDK、HTTP）、代码标识符等
- 图片文件名、变量名
第 4 步：应用生成
python scripts/apply.py <html根目录> <翻译json> <输出目录> --lang <代码>
python scripts/apply.py your-site/ your-site/locales/en-US.json your-site/en --lang en
python scripts/apply.py your-site/ your-site/locales/ja-JP.json your-site/ja --lang ja
每种语言生成一个独立目录，内含译文后的 HTML，共享根目录的 css 与图片（子目录自动补 ../ 前缀）。
apply 会：① 把每个文本节点替换为译文 ② 改 <html lang> ③ 补资源相对路径。
缺失译文的 key 会回退原文（不破版）并告警。
第 5 步：完整性检查
python scripts/check.py <locales目录>
输出每种语言的完成度百分比、缺失/空值/疑似漏翻（译文与原文相同）的 key。
全部 100% 才算完成。之后抽检这些关键页面：
- 含代码块的页（验证代码未被破坏）
- 含
<table> 的页（验证单元格翻译）
- 首页/目录页（验证链接与封面文案）
- 含内联
<strong>/<a> 混排的页（验证嵌套标签未乱）
脚本说明
| 脚本 | 作用 | 关键设计 |
|---|
scripts/extract.py | 扫描 HTML 提取可翻译文本 | 共享 htmlscanner，跳过代码块/URL，跨文件重复归并 common key |
scripts/apply.py | 用译文回填生成语言目录 | 字符串精确替换；用「已占用区间」追踪避免重叠替换（如 §短标题 嵌在 §完整标题内）；标签结构逐字保留；缺译文回退原文 |
scripts/check.py | 检查翻译完整性 | 对比 key 集合，报告缺失/空值/漏翻 |
scripts/htmlscanner.py | extract 与 apply 共用的扫描器 | 杜绝「提取漏抓、回填却看到」的不一致 |
scripts/zhconv.py | 简→繁转换（可选，生成 zh-TW 时用） | 词级两岸术语替换 + 字符级字形映射，零依赖 |
关于字符映射类语言（如 zh-TW、ja-JP 的速成版）：
zhconv.py 与示例 ja_dict.py 采用「术语表 + 字形映射」，对标题/导航/封面/术语质量高，
但长正文段落可能残留少量未转换字（尤其 ja-JP 的中日汉字混排）。
生产级译文建议：结构性文本用字符映射即可，长正文段落由你（LLM）按 references/glossary.md 逐段精译后填入对应 json。
输出结构示例
your-site/
├─ index.html (原版，保持不动)
├─ page1.html ...
├─ style.css (多语言共享)
├─ assets/ (图片等资源，多语言共享)
├─ locales/
│ ├─ zh-CN.json (翻译源)
│ ├─ en-US.json (英文译文)
│ ├─ ja-JP.json (日文译文)
│ ├─ zh-TW.json (繁中译文)
│ ├─ _index.json (定位用，勿改)
│ └─ _common.json (公共 key 参考)
├─ en/ ← 英文站 (lang="en")
├─ ja/ ← 日文站 (lang="ja")
└─ zh-TW/ ← 繁中站 (lang="zh-TW")
注意事项
- 零侵入：原中文版 HTML 不改动，译文输出到独立子目录
- 不碰构建脚本：若站点由 Markdown/脚本生成（如
generate_site.py），本 skill 只处理已生成的 HTML，不改源码生成逻辑
- 代码安全优先：
<pre><code> 默认整体跳过；若用户显式要求翻译代码注释，需人工逐条确认
- 术语一致性：跨页重复的导航词（目录/上一章/下一章）由 common key 统一驱动，勿分散翻译
- 翻译完务必运行 check.py + 抽检，确认无破版
