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

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

​

Locale 能力

​

預期結構

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

​

在 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 時，default_locale 是否存在
• _locales/<default>/messages.json 是否存在
• Locale 檔案的 JSON 是否有效
• Manifest 中的 __MSG_*__ 參考是否對應到預設 locale 的鍵

​

排除缺少的 locale 鍵

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

​

最佳實務

• 跨 locale 維持 messages.json 的鍵一致。
• 先更新預設 locale，再把鍵傳播到其他 locale。
• 在持續整合（CI）中驗證 locale JSON，以在打包前抓出格式錯誤的檔案。
• 把 locale 檔案放在 manifest 附近（manifestDir/_locales），以維持可預期的解析。

​

後續步驟

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