HTML国际化需随敏捷迭代同步演进：新增UI文本须即时补全所有语言包键值，键名扁平化并按模块拆分文件，CI校验键一致性，QA强制多语言及fallback测试。
HTML国际化在敏捷开发中不是一次性配置完就扔进仓库的事，而是要随着每个迭代同步演进——文案增删、键名调整、语言包补漏，都得跟功能开发节奏对齐，否则两周后就会发现 en.json 里多了 12 个新键，zh.json 还是空的。
每次新增 UI 文本必须同步更新所有语言包
前端加一个按钮或提示语，不能只写 HTML 和英文文案，必须立刻补全所有已支持语言的 JSON 键值对。否则 QA 测试时切到日文环境，看到 btn_submit 原样显示，不是“送信”，就是 bug。
- 新元素必须带
data-i18n属性，值为统一英文键名（如"modal_close_confirm"），不能用中文或拼音作键 - 对应键必须出现在
locales/en.json、locales/zh.json、locales/ja.json等所有语言文件顶层，哪怕先填空字符串"modal_close_confirm": "" - CI 流程里加校验脚本：对比各语言 JSON 的键数量与键名集合，不一致则构建失败（可用
jq或简单 Node.js 脚本实现）
语言包结构扁平 + 按模块拆分，避免 merge 冲突
把所有翻译塞进一个 locales/en.json 里，多人同时改注册页和支付页文案，git merge 时几乎必然冲突。键名嵌套（如 {"form": {"login": {"submit": "Log in"}}）还会让 JS 查找变慢、fallback 逻辑复杂。
- 按功能域拆成多个文件：
locales/common.json、locales/auth.json、locales/checkout.json - 所有文件保持扁平结构，键名不嵌套，例如直接
"auth_forgot_password": "Forgot password?" - 加载时用
Promise.all([import('./locales/common.json'), import('./locales/auth.json')])并行获取，首屏不卡
QA 阶段强制语言切换测试 + fallback 验证
敏捷迭代交付前，不能只测默认语言。用户语言设置异常、JSON 加载失败、键缺失——这些情况在真实环境高频发生，但本地开发常被忽略。
立即学习“前端免费学习笔记（深入）”；
- 测试 checklist 必须含：切到
zh-HK（非主简体）、ar（RTL）、xx-XX（不存在语言码），观察是否 fallback 到zh→en - 手动断网或 mock
fetch('./locales/zh.json')返回 404，确认页面不空白，未翻译处显示键名（如[auth_login]）或兜底文案 - 检查
document.documentElement.lang是否实时更新，且所有含lang属性的子节点（如<p lang="ja">）未被错误覆盖
最易被跳过的点：动态插入内容（AJAX 弹窗、表格行、Tab 页签）没调用翻译函数，导致新 DOM 永远显示英文键；还有 placeholder、title、alt 这类属性没用 data-i18n-placeholder 单独标记，切语言后依然硬编码。
