Locale 與國際化

​

範本範例

​

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 中宣告 locale 的範例

{
  "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 變更會觸發擴充功能重新載入行為（hard reload），而不是元件式的 hot module replacement（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"
  }
}

​

打包行為

​

最佳實務

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

​

後續步驟

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

​

影片導覽