语言区域与国际化

​

模板示例

​

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

deno run -A npm:extension@latest create my-extension --template=action-locales

​

Locale 能力

​

期望的目录结构

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

​

传统布局：_locales 放在 manifest 旁边

​

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."
  }
}

​

在运行时用 chrome.i18n 读取字符串

const title = chrome.i18n.getMessage("extension_name");
document.title = title;

{
  "greeting": {
    "message": "Hello, $NAME$",
    "placeholders": {
      "name": {
        "content": "$1"
      }
    }
  }
}

chrome.i18n.getMessage("greeting", ["Ada"]);

• chrome.i18n.getUILanguage() 返回浏览器的语言。
• chrome.i18n.getAcceptLanguages() 返回用户接受的语言列表。

​

Extension.js 不会替你替换占位符

• 在 manifest.json 中，它会把每个引用与默认 locale 比对，并报告缺失的那些。
• 在打包时，它会解析 __MSG_*__ 名称，让 zip 文件名带上翻译后的名字。
• 在 HTML、JavaScript 和 JSON 文件中，它不会改动文本。

<h1 data-i18n="extension_name"></h1>

for (const node of document.querySelectorAll("[data-i18n]")) {
  node.textContent = chrome.i18n.getMessage(node.dataset.i18n);
}

​

browser.i18n 写法

​

输出路径

_locales/<locale>/messages.json

​

开发期行为

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

​

校验行为

• 存在 _locales 文件夹但 manifest 中没有 default_locale 会让构建失败，因为浏览器会拒绝这种组合
• _locales/<default> 及其 messages.json 是否存在
• 每个 locale 的 messages.json 的 JSON 合法性
• manifest 中的 __MSG_*__ 引用是否与默认 locale 的键匹配

• 预定义的 @@ 消息，例如 __MSG_@@ui_locale__，是豁免的，因为它们由浏览器提供。
• 消息键内部允许出现 @ 字符，这与 Chrome 对消息名的语法一致。

​

排查缺失的 locale 键

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

​

打包行为

​

最佳实践

• 保持 messages.json 的键在各 locale 之间一致。
• 先更新默认 locale，然后再把键扩散到其他 locale。
• 在持续集成（CI）中校验 locale JSON，在打包前发现损坏的文件。
• 把 _locales 放在项目根目录，这也是浏览器和打包步骤读取的位置。

​

下一步

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

​

视频讲解