Locale 與國際化

國際化（通常簡寫為 i18n）由兩個部分組成：一個存放你翻譯內容的 _locales 資料夾，以及在執行階段讀取它們的 chrome.i18n API。 Extension.js 會讀取你專案根目錄的 _locales 資料夾，並驗證每個被宣告的 locale 都有 messages.json。它會把 locale JSON 資產輸出到對應瀏覽器的 build。在開發期間，它能在不重新啟動的情況下捕捉任何 locale 檔案的編輯。

範本範例

`action-locales`

透過 _locales 支援查看已在地化的擴充功能中繼資料與 UI 字串。

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

儲存庫：extension-js/examples/action-locales

Locale 能力

能力	你會獲得的成果
Locale 探索	在專案根目錄偵測 `_locales/<locale>/messages.json`
驗證	捕捉缺少的預設 locale 檔案與無法解析的 `__MSG_*__` 鍵
Build 輸出對應	以預期的擴充功能輸出結構輸出 locale 檔案
開發期 watch 支援	在 locale 檔案變更時於開發期重新載入

預期結構

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

manifest.json 中的 default_locale 應對應到一個既存的 _locales/<default>/messages.json。

舊版配置：`_locales` 放在 manifest 旁邊

即使你的 manifest 位於 src/ 之類的子資料夾，專案根目錄仍是 _locales 的正規位置。放在巢狀 manifest 旁邊的 _locales 資料夾依然可以建置。編譯器會發出 LocalesLayoutWarning，要求你把它移到根目錄。瀏覽器是從擴充功能根目錄讀取 locale，所以放在根目錄才與實際出貨的內容一致。

在 `manifest.json` 中宣告 locale 的範例

以下示範如何在 manifest.json 中宣告 locale：

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

然後你會在 _locales 資料夾中為每個 locale 放置對應的 JSON 檔案：

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

`messages.json` 檔案範例

翻譯用的 messages.json 檔案範例：

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

在執行階段用 chrome.i18n 讀取字串

__MSG_*__ 佔位符是 manifest 的能力。瀏覽器只會在 manifest.json，以及 manifest 宣告的 CSS 檔案中展開它們。其他地方都不會。你自己程式碼中的每個字串，都要呼叫這個 API：

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

替換內容來自第二個參數：

_locales/en/messages.json

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

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

另外兩個呼叫也很有用：

chrome.i18n.getUILanguage() 會回傳瀏覽器的語言。
chrome.i18n.getAcceptLanguages() 會回傳使用者接受的語言。

Extension.js 不會替你替換佔位符

Extension.js 會讀取 __MSG_*__ 參照，但從不改寫它們。

在 manifest.json 中，它會把每個參照與預設 locale 比對，並回報缺少的項目。
在打包時，它會解析 __MSG_*__ 名稱，讓 zip 檔名帶上翻譯後的名稱。
在 HTML、JavaScript 與 JSON 檔案中，它不會更動文字。

所以你寫進 HTML 檔案的佔位符，會以字面文字出貨。請改為在腳本中設定這個字串：

pages/popup.html

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

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

同樣的限制也適用於內容腳本以 <style> 文字形式插入的 CSS。__MSG_@@extension_id__ 在那裡不會展開。Extension.js 已經會把那段 CSS 中的 url() 參照改寫到擴充功能根目錄，因此你不需要這個佔位符。

`browser.i18n` 寫法

Firefox 與 Safari 原生提供 browser.i18n。在 Chromium 上，Extension.js 透過 webextension-polyfill 提供 browser 命名空間，因此 browser.i18n.getMessage 在每個目標上都能運作。細節請閱讀跨瀏覽器相容性。

輸出路徑

Extension.js 會把 locale JSON 檔案輸出到：

_locales/<locale>/messages.json

開發行為

Extension.js 把 locale JSON 檔案加入編譯相依，並監看它們。
Locale 變更會觸發擴充功能重新載入行為（hard reload），而不是元件式的 hot module replacement（HMR）。
當必要的 locale 檔案缺失或無效時，Extension.js 會提出帶有可採取行動的診斷訊息並讓驗證失敗。

驗證行為

Extension.js 會驗證：

有 _locales 資料夾但 manifest 中沒有 default_locale 會讓建置失敗，因為瀏覽器會拒絕這種組合
_locales/<default> 及其 messages.json 是否存在
每個 locale 的 messages.json 的 JSON 是否有效
Manifest 中的 __MSG_*__ 參考是否對應到預設 locale 的鍵

__MSG_*__ 掃描有兩個細節：

預先定義的 @@ 訊息，例如 __MSG_@@ui_locale__，會被豁免，因為它們由瀏覽器提供。
訊息鍵內部允許出現 @ 字元，這與 Chrome 對訊息名稱的語法一致。

排除缺少的 locale 鍵

如果你的 manifest 使用 __MSG_extension_description__，請確保預設 locale 檔案包含 extension_description：

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

如果預設 locale 沒有定義該鍵，Extension.js 會顯示診斷訊息說明這個不一致。

打包行為

當你用 --zip 或 --zip-source 建置時，Extension.js 會在打包時再次檢查預設 locale。宣告了 default_locale 卻沒有對應 messages.json 的 manifest 會產生警告，因為商店會拒絕缺少預設 locale 的套件。 zip 檔名來自 manifest 的 name。__MSG_*__ 形式的 name 會依預設 locale 的 messages.json 解析，所以封存檔帶的是翻譯後的名稱，而不是佔位符。

最佳實務

跨 locale 維持 messages.json 的鍵一致。
先更新預設 locale，再把鍵傳播到其他 locale。
在持續整合（CI）中驗證 locale JSON，以在打包前抓出格式錯誤的檔案。
把 _locales 放在專案根目錄，那也是瀏覽器與打包步驟讀取的位置。

後續步驟

在 dev 更新行為中了解更新結果。
繼續閱讀開發中的 JSON。
進一步了解 manifest 開發行為。

Introduction

Browser extension fundamentals

Getting started

範本

Compare and migrate

Commands reference

Features

Browsers

Languages and frameworks

Integrations

Workflows

Machine contracts

Publish to the stores

Debugging

Implementation guide

Community

範本範例

`action-locales`

Locale 能力

預期結構

舊版配置：`_locales` 放在 manifest 旁邊

在 `manifest.json` 中宣告 locale 的範例

`messages.json` 檔案範例

在執行階段用 chrome.i18n 讀取字串

Extension.js 不會替你替換佔位符

`browser.i18n` 寫法

輸出路徑

開發行為

驗證行為

排除缺少的 locale 鍵

打包行為

最佳實務

後續步驟

影片導覽

​範本範例

​action-locales

​Locale 能力

​預期結構

​舊版配置：_locales 放在 manifest 旁邊

​在 manifest.json 中宣告 locale 的範例

​messages.json 檔案範例

​在執行階段用 chrome.i18n 讀取字串

​Extension.js 不會替你替換佔位符

​browser.i18n 寫法

​輸出路徑

​開發行為

​驗證行為

​排除缺少的 locale 鍵

​打包行為

​最佳實務

​後續步驟

​影片導覽

範本範例

`action-locales`

Locale 能力

預期結構

舊版配置：`_locales` 放在 manifest 旁邊

在 `manifest.json` 中宣告 locale 的範例

`messages.json` 檔案範例

在執行階段用 chrome.i18n 讀取字串

Extension.js 不會替你替換佔位符

`browser.i18n` 寫法

輸出路徑

開發行為

驗證行為

排除缺少的 locale 鍵

打包行為

最佳實務

後續步驟

影片導覽