用Node.js脚本自动提取HTML中待翻译文本，需用cheerio解析HTML，筛选data-i18n元素提取key和源文本，跳过script/style，输出UTF-8编码JSON；构建时再据此生成多语言HTML文件。
如何用 Node.js 脚本自动提取 HTML 中的待翻译文本
直接解析 HTML 提取 data-i18n 属性或特定标签内容是最轻量、可控的方式，比引入完整 i18n 框架更适配纯静态 HTML 项目。关键不是“支持多语言”，而是“不让翻译漏掉、不手动改 HTML”。
- 用
cheerio加载 HTML，筛选含data-i18n的元素，提取其data-i18n值作为 key，文本内容（或title/alt等属性）作为默认 source value - 对没有
data-i18n但需翻译的文本（如<p>Hello</p>），可约定扫描lang="en"或 class="translatable" 的节点，避免误提 - 输出 JSON 格式：key 保持唯一（建议用路径+序号生成，如
"header.nav.home": "Home"），value 是源语言原文，便于后续交由翻译平台或人工核对 - 注意：
<script>和<style>内容必须跳过，否则会把 JS 字符串或 CSS 注释当作文本提取
构建脚本如何生成多语言 HTML 文件
不是靠运行时 JS 切换语言，而是构建时生成 index.zh.html、index.ja.html 等物理文件——部署简单、CDN 友好、SEO 可控。
- 读取原始
index.html，用cheerio加载；再读取对应语言的翻译 JSON（如zh.json），遍历所有含data-i18n的节点 - 对每个节点，用其
data-i18n值查 JSON，找到对应翻译；若缺失，保留原文或写入占位符（如[MISSING: header.title]），方便定位漏翻 - 替换文本时区分场景：
<span data-i18n="greeting">Hi</span>替换 innerText；<img data-i18n="logo.alt" alt="Logo">替换alt属性 - 不要覆盖原始 HTML 的结构和注释——
cheerio.load(html, { xmlMode: false, decodeEntities: false })可保留原始编码和格式
为什么不用 Webpack / Vite 插件而选自研脚本
当项目只有几页静态 HTML、无 JS 构建流程时，加 Webpack 就像为螺丝刀配起重机——启动慢、配置碎、调试难，反而增加维护成本。
- Webpack 的
html-webpack-plugin+i18n-webpack-plugin依赖 loader 链，一旦 HTML 里有内联<script>或特殊模板语法（如{{name}}），容易解析失败或丢内容 - Vite 的
@intlify/vite-plugin-vue-i18n默认面向 Vue，对纯 HTML 支持弱，且生成的是运行时资源，不符合“构建即多语言文件”的需求 - 自研脚本用
fs+cheerio+path三件套，不到 100 行，可直接node build-i18n.js运行，CI 中也稳定 - 例外情况：如果已有 Vue/React 项目，那就该用对应框架的 i18n 方案，别硬套 HTML 脚本
常见错误：HTML 特殊字符与编码导致翻译错乱
中文引号、破折号、 、& 等在提取和写入过程中极易被二次转义或丢失，这是自动化中最隐蔽的坑。
立即学习“前端免费学习笔记（深入）”；
- 提取时：用
$.text()而非.html()获取文本，避免把 - 写入时：用
elem.text(translation)而不是elem.html(translation)，防止翻译内容里的<被当成标签解析 - JSON 文件必须用 UTF-8 编码保存（编辑器确认），Node.js 读取时显式指定
encoding: 'utf8'，否则 Windows 下常出现乱码 - 如果原文含
"或'，确保 JSON value 中已正确转义，否则写回 HTML 后属性值截断（如<div title="He said "Hi"">）
真正麻烦的不是多语言本身，而是 HTML 解析边界模糊——标签嵌套、自闭合、注释位置、空格处理，都会让 cheerio 输出和原始不一致。每次生成后建议用 diff 工具比对原始与目标 HTML，重点关注结构变更而非仅文本。
