HTML应用国际化开发的自动化构建脚本

用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 后属性值截断（如 <p title="He said "Hi"">）

真正麻烦的不是多语言本身，而是 HTML 解析边界模糊——标签嵌套、自闭合、注释位置、空格处理，都会让 cheerio 输出和原始不一致。每次生成后建议用 diff 工具比对原始与目标 HTML，重点关注结构变更而非仅文本。