语言区域与国际化

​

模板示例

​

action-locales

npx extension@latest create my-extension --template=action-locales

pnpx extension@latest create my-extension --template=action-locales

yarn dlx extension@latest create my-extension --template=action-locales

bunx extension@latest create my-extension --template=action-locales

bunx extension@latest create my-extension --template=action-locales

​

Locale 能力

​

期望的目录结构

manifest.json
_locales/
  en/
    messages.json
  fr/
    messages.json

​

manifest.json 中的 locales 声明示例

{
  "manifest_version": 3,
  "name": "My Extension",
  "version": "1.0.0",
  "default_locale": "en",
  "description": "__MSG_extension_description__"
}

_locales/
└── en/
    └── messages.json

​

messages.json 文件示例

{
  "extension_name": {
    "message": "My Extension"
  },
  "extension_description": {
    "message": "This is a localized description of my extension."
  }
}

​

输出路径

_locales/<locale>/messages.json

​

开发期行为

• Extension.js 会把 locale JSON 文件加入编译依赖并监视它们。
• Locale 变更会触发扩展的重载行为（硬重载），而不是组件式的热模块替换（HMR）。
• 当必需的 locale 文件缺失或无效时，Extension.js 会以可操作的诊断信息让校验失败。

​

校验行为

• 当项目使用 _locales 时是否存在 default_locale
• _locales/<default>/messages.json 是否存在
• locale 文件的 JSON 合法性
• manifest 中的 __MSG_*__ 引用是否与默认 locale 的键匹配

​

排查缺失的 locale 键

{
  "extension_description": {
    "message": "Localized extension description"
  }
}

​

最佳实践

• 保持 messages.json 的键在各 locale 之间一致。
• 先更新默认 locale，然后再把键扩散到其他 locale。
• 在持续集成（CI）中校验 locale JSON，在打包前发现损坏的文件。
• 把 locale 文件放在 manifest 附近（manifestDir/_locales），以获得可预测的解析。

​

下一步

• 在 dev 更新行为 中了解更新结果。
• 继续阅读 开发中的 JSON。
• 进一步了解 manifest 开发行为。