.pot、.po、.mo：WordPress 語言檔的作用與翻譯方式

譯文完成後未在網站上生效，常見原因是沒有編譯，或檔名不正確。這兩項在本頁最後幾節說明。

三種檔案

• .pot：範本。包含佈景主題或外掛中所有可翻譯的字串，譯文為空。由開發者從原始碼產生，使用時複製，不直接修改。
• .po：某一種語言的譯文。純文字，每條原文下方是對應譯文。翻譯工作在這個檔案中進行。
• .mo：.po 的編譯結果。二進位格式，不供人閱讀。WordPress 載入的是這個檔案。

WordPress 6.5 起還有第四種格式：.l10n.php。它載入更快，存在時優先使用，.mo 作為備用。該檔案無需手動產生，WordPress 會自動產生，因此語言目錄中可能出現未手動加入的檔案。

翻譯 .pot 檔的步驟

1. 找到 .pot 檔。它通常位於外掛或佈景主題目錄下的 languages/ 中。
2. 依下一節的命名規則，將其複製為目標語言的 .po 檔。
3. 翻譯其中的條目，可在 PO 編輯器中逐條翻譯，也可批次翻譯。每個佔位符都必須與原文完全一致。
4. 將 .po 編譯成 .mo，並把兩個檔案放到 WordPress 讀取的位置。未安裝 gettext 時，可使用免費的瀏覽器編譯工具。

檔案較大時，PO / POT 翻譯工具可一次翻譯整個檔案，並匯出為相同格式。工具只傳送字串，不上傳檔案。

檔案命名

WordPress 依 {文字域}-{locale}.mo 尋找檔案。檔名只要有一個字元不同，WordPress 就不會載入該檔案，並直接退回英文，不顯示任何錯誤或提示。這是譯文完成後不生效的最常見原因。

• 文字域由外掛或佈景主題自身定義，例如 woocommerce、twentytwentyfive、my-cool-plugin。它宣告在外掛標頭，不一定與資料夾名稱相同。
• locale 使用 WordPress 自己的地區設定代號，而不是兩位語言碼。繁體中文為 zh_TW、英語為 en_US、法語為 fr_FR；日語為 ja、阿拉伯語為 ar、芬蘭語為 fi，不帶地區碼。
• 原始檔名已包含 locale 時（如 woocommerce-en_US.po），需先去掉原有 locale 再加上新的，否則會得到 woocommerce-en_US-zh_TW.mo，無法對應任何語言。

檔案存放位置

WordPress 會從兩個位置載入譯文，兩者在外掛或佈景主題更新時的表現不同。

• wp-content/languages/plugins/ 與 wp-content/languages/themes/：建議使用。 WordPress 優先讀取這裡，外掛或佈景主題更新不會覆蓋其中的檔案。
• 外掛或佈景主題自身的 languages/ 目錄：同樣會被讀取，但下次更新會替換整個目錄，譯文隨之遺失。

譯文未生效的排查順序

1. 確認存在 .mo 檔。只有 .po 檔不會產生任何效果。
2. 確認檔名嚴格符合 {文字域}-{locale}.mo。文字域以外掛標頭為準，locale 以 WordPress 的 locale 清單為準。
3. 確認網站語言已在 設定 → 一般 中設為該語言。
4. 確認檔案位於 wp-content/languages/…。只放在外掛目錄中的檔案，會在外掛更新時被刪除。
5. 仍未生效時，清除物件快取與頁面快取。譯文在每個請求中只載入一次，並會被快取。

佔位符

顯示 %1$s 筆，共 %2$s 筆 這類字串包含由 PHP 填入數值的佔位符。譯文中缺少佔位符、未使用編號形式就調換順序，或把 %s 寫成全形的 ％s，都不是顯示問題，而是頁面上的執行階段錯誤。部署檔案前應檢查佔位符；具備佔位符檢查的編譯工具會標出這類錯誤。