为前端插件/侧边栏提供跟随宿主应用语言偏好的国际化方案，替代…

# Chrome插件侧边栏i18n接入方案（中/英/日三语）

一、方案选型

• 方案A（推荐）：Chrome Extensions Manifest V3 原生 chrome.i18n + _locales/{en,zh_CN,ja}/messages.json
• 方案B：自建词典对象 + 切换逻辑（更灵活，可实时切换无需重启扩展）
• 结合两者：用原生方案兜底默认语言，运行时用自建词典实现无刷新实时切换

二、目录结构

```

_locales/

zh_CN/messages.json

en/messages.json

ja/messages.json

sidebar/

dict/

zh_CN.js / en.js / ja.js

i18n.js # 切换核心逻辑

```

三、词典命名与内容规范

• 200条文案建议按模块分组命名：search_placeholder、price_compare_title、btn_favorite 等，避免魔法字符串
• messages.json 格式：{ "key": { "message": "文案", "description": "给翻译者看的说明" } }
• 侧边栏自建词典建议导出为 ES Module，保持与 messages key 一一对应，便于双方案对照

四、宿主语言偏好获取（淘宝开放平台场景）

• 侧边栏需读取淘宝宿主页/开放平台返回的语言偏好字段（如用户所在站点或TOP接口返回的 locale 信息），优先级建议：

1. 插件内用户手动选择（存 chrome.storage.sync）

2. 淘宝宿主语言偏好

3. chrome.i18n.getUILanguage() 兜底

• 注意 zh-CN/zh-TW/en/ja 的 locale 映射，淘宝站点 locale 与 Chrome locale 命名不完全一致，需写一层映射函数

五、实时切换实现要点

• 切换时不 reload 页面：维护一个 applyLocale(locale) 函数，遍历侧边栏 DOM 中带 data-i18n 属性的节点替换 textContent；placeholder 用 dataset.i18nPlaceholder 区分
• 动态渲染的文案统一走 t(key) 函数，切换后触发一次重新渲染事件即可
• 监听 chrome.storage.onChanged，多窗口/多iframe侧边栏同步生效

六、工程化与校验

• 200条文案手工维护易漏译，建议加一个脚本对比三份词典 key 差集，接入 CI
• 文案长度差异大（日文常更长）：CSS 预留弹性宽度，避免截断；测试时重点检查按钮和标签
• 数字/价格格式化用 Intl.NumberFormat(locale)，不要硬编码 ¥/$ 符号

七、验证清单

• [ ] 三语切换无闪烁、无残留旧文案
• [ ] 手动选择优先级覆盖宿主偏好
• [ ] 缺失 key 有 fallback 且控制台告警

如需，我可以直接给出 i18n.js 核心代码骨架和 messages.json 样例。