使用指南 7:讓更多語言的讀者使用部落格

$ 發布 2026-11-13 | | 更新 2026-11-14
上下文: 依實際設定解釋語言啟停、預設語言、首頁路由、回退行為、新語言整合及文章和碎片的多語言關聯。

選擇語言、調整首頁地址、填寫在地化文字,再為文章和碎片補上譯文。


輸出
字數 2.9k 詞元 3.8k

本篇是入門教學的第 7 / 8 篇。檢視完整教學順序 · 依欄位查設定字典。

你可以先只寫一種語言,以後再添加譯文。主題提供多語言介面和路由,但不負責自動翻譯文章;啟用一個語言、修改介面文字、發佈一篇譯文,是三個不同操作。

下面所有設定都合併到 src/site.config.ts 已有的 defineThemeConfig({...}) 物件中。保留原來的 i18n 和其他個人設定,不要重複追加同名物件。

1. 先決定需要哪些語言

預設啟用九種語言,預設語言是 en:

代碼 語言
en English
zh 简体中文
zh-hant 繁體中文
ja 日本語
ko 한국어
es Español
pt-br Português (Brasil)
de Deutsch
ru Русский

如果想只保留中文和英文,同時將預設語言改為中文,可以選擇下面的設定;不需要這些調整時保留專案預設值即可:

i18n: {
  defaultLocale: 'zh',
  locales: {
    zh: { meta: { enabled: true } },
    en: { meta: { enabled: true } },
    ja: { meta: { enabled: false } },
    ko: { meta: { enabled: false } },
    es: { meta: { enabled: false } },
    'pt-br': { meta: { enabled: false } },
    de: { meta: { enabled: false } },
    ru: { meta: { enabled: false } },
    'zh-hant': { meta: { enabled: false } },
  },
},

省略一個語言不會將它關閉,因為設定會與預設值合併。必須明確寫 meta.enabled: false;預設語言始終啟用,不能一邊指定 defaultLocale: 'zh',一邊期望通過關閉 zh 隱藏它。

關閉語言會移除其主題語言入口並停止生成相應標準頁面,不刪除該目錄中的文章檔案。重新啟用後,保留的內容可以再次生成。改語言代碼則會改變目錄和網址,不等於只改一個顯示名稱;已有網站需要自己處理舊連結。

2. 選擇預設語言首頁的網址

在現有 i18n 中加入或修改 routing:

i18n: {
  defaultLocale: 'zh',
  routing: { defaultLocalePrefix: 'never' },
},

以預設語言 zh 為例:

設定 / /zh/ /en/
'always',主題預設 靜態跳轉到 /zh/ 中文首頁 英文首頁(需啟用)
'never' 直接顯示中文首頁 靜態跳轉到 / 英文首頁(需啟用)

預設語言由設定確定,不會根據訪客瀏覽器語言自動改成另一種。跳轉是建置出來的 HTML 跳轉頁,不需要額外的應用伺服器;瀏覽時可能短暫看到跳轉提示。

這個設定只影響預設語言首頁。 中文部落格、文章、About、Decoder 和 Fragments 仍保留 /zh/ 前綴,例如 /zh/blog/my-first-post/,不會自動變成 /blog/my-first-post/。更改預設語言也不會移動或翻譯已有內容檔案。

3. 給不同語言填寫首頁和介面文字

在對應語言下設定自己的文字,例如:

i18n: {
  locales: {
    zh: {
      meta: { label: '简体中文' },
      site: {
        homeTitle: '小林的数字花园',
        hero: '记录开发、阅读和生活。',
      },
      messages: {
        siteDescription: '小林的个人博客,分享项目和学习笔记。',
        nav: { home: '首页', blog: '文章', about: '关于我' },
      },
    },
    en: {
      site: {
        homeTitle: "Lin's Digital Garden",
        hero: 'Notes on code, books and everyday life.',
      },
      messages: { siteDescription: 'Projects and learning notes by Lin.' },
    },
  },
},
  • meta.label 是語言選單名稱。把“简体中文”改為“中文”,不會把代碼 zh 或網址也改名。
  • site.homeTitle 只改變目前語言首頁的可見大標題;全站名稱仍由頂層 site.title 或環境覆寫值決定。
  • site.hero 是首頁大標題下面的可見介紹。
  • messages.siteDescription 是首頁中繼描述,不是可見介紹;只改頂層 site.description 不一定替換內建首頁描述。
  • messages.nav 修改對應介面入口的文字,不改變路由或文章內容。

同樣,i18n.locales.<locale>.about 修改該語言的 About 內容,messages 下各模組修改對應介面文字。About 和 Decoder 等頁面仍受全站功能開關控制,不會因為寫了譯文就自動開啟。具體內容範例見頁面與功能自訂。

語言中繼資料和預設首頁地址可查語言字典;首頁三種文字的區別見首頁字典。

4. 理解沒有填寫的欄位從哪裡來

meta.fallback 用來選擇設定回退語言。例如希望簡體中文缺少設定時參考英文,可合併:

i18n: {
  locales: {
    zh: { meta: { fallback: ['en'] } },
  },
},

這裡的 en 必須在專案的語言設定中存在。預設語言會被補進非預設語言的必要回退鏈;自己、重複項和不存在的語言會被過濾。陣列會整體替換,所以填寫多個回退語言時,要一次寫出希望使用的順序。

回退的具體規則並非所有欄位都一樣:

內容 目前行為
一般 messages 從內建英文開始,按回退鏈合併內建語言包和個人覆寫,目前語言優先;內建譯文也參與合併
首頁 homeTitle 依次查找目前語言及回退語言的非空、去除首尾空白後的標題,最後使用全站名稱
首頁 hero 查找目前語言及回退語言的已定義值;'' 是主動清空,不會繼續找下一語言
About 設定 從預設 About 開始,按回退鏈合併對應語言的個人 About 設定
首頁 messages.home.transmission 單獨使用目前語言個人設定 → 英文個人設定 → Knock, knock.,不走一般文字的完整回退鏈

所以,把英文導覽文字改掉,不代表已有中文內建導覽也會變成英文設定裡的文字。要明確改變一種語言的介面,應在該語言下覆寫。關閉某語言的頁面也不等於刪除其設定;仍在回退鏈中的設定可以參與補齊。

回退只補設定和介面文字:不會把英文文章自動放進中文部落格,也不會自動建立另一語言的檔案。不要把它當作內容翻譯服務。

5. 添加一個新的語言

例如添加法語,在現有 locales 中加入 fr,保留前面已啟用和關閉的語言設定:

i18n: {
  locales: {
    fr: {
      meta: {
        label: 'Français',
        hreflang: 'fr',
        ogLocale: 'fr_FR',
        enabled: true,
        fallback: ['en'],
      },
      site: {
        homeTitle: 'Le jardin de Lin',
        hero: 'Notes de lecture et projets.',
      },
      messages: {
        siteDescription: 'Le blog personnel de Lin.',
        nav: { home: 'Accueil', blog: 'Articles', about: 'À propos' },
      },
    },
  },
},

fr 是目錄和路由使用的代碼。建議使用規範的小寫代碼;建立指令接受兩到三位字母和選用的一段連字號後綴,例如 fr、pt-br、zh-hant,不能寫路徑或空格。範例沿用現有預設語言,不會把法語自動設為預設。

hreflang 是頁面語言替代連結的語言識別碼;省略時使用語言代碼。ogLocale 是 Open Graph 使用的語言地區識別碼,格式與路徑代碼不同,範例為 fr_FR。這些中繼資訊不會翻譯內文,也不保證搜尋引擎收錄。

新語言沒有內建完整翻譯包。上面的片段只翻譯幾個入口,其他文字會回退;需要完整法語介面,還需補充自己使用的搜尋、分頁、評論提示、工具和 About 等模組文字。先從實際頁面上會出現的內容開始,不必為了顯示一篇文章先修改主題實作。

6. 為文章補一份譯文

同時建立中文和英文文章範本:

npm run new-post -- my-first-post --locales zh,en

在 src/content/blog/zh/my-first-post.md 寫中文,在 src/content/blog/en/my-first-post.md 寫英文。新語言範例可使用 npm run new-post -- french-note --locales fr,生成後自己填寫內容。

已有中文文章要補譯時,也可以複製到目標語言目錄並保留檔案主名,再翻譯標題、簡介和內文。相對圖片路徑從新檔案位置計算,複製到不同目錄層級後需要檢查路徑。同名檔案已存在時建立指令跳過,不覆寫舊稿。

文章譯文依靠語言目錄之外的完整 slug 關聯。例如 zh/my-first-post 與 en/my-first-post 是譯文;把英文檔案名改為 my-story 就成為不同文章,標題相同也不會自動配對。嵌套目錄同樣要一致。

文章頁語言選單中,有同 slug 的目標語言文章時進入譯文;缺少時進入該語言部落格列表。搜尋引擎用的文章語言替代連結只宣告真正存在且已啟用的譯文,不把列表頁假稱為另一種語言的文章。

--locales 只建立指定語言檔案,不會啟用語言。省略時先檢查 ANGLEFEINT_LOCALES 環境變數,未設定則使用專案啟用語言;明確參數優先于環境變數。建立範本和翻譯內文是分開的步驟。

7. 碎片和其他頁面的語言切換

碎片譯文使用相同 frontmatter id,不靠相同檔案名關聯。後續補譯時複製原檔案到目標語言目錄,保留 id 和 pubDate,再翻譯標題與內文。再次執行 new-fragment 會建立新身分,不能用來補同一條的譯文。

同一次 npm run new-fragment -- --locales zh,en 會為兩種語言生成共享 ID 和時間戳的範本。碎片列表的語言切換始終進入目標語言第一頁,不保證直接定位同一條譯文。完整規則見發佈一條碎片。

文章評論的多語言共享需要另外啟用 theme.comments.shareAcrossLocales,預設關閉;碎片評論則按相同 ID 共享。介面語言和討論關聯是兩件事,評論內文也不會自動翻譯,見讓讀者留下評論。

new-page 生成的自訂 Astro 頁面會為啟用語言生成路由,但只提供一份頁面原始檔案;你需要根據語言提供相應內容,不會自動為每種語言複製或翻譯一套頁面。

8. 修改後檢查哪些結果

先在 dev 中逐個打開自己啟用語言的首頁,檢查選單名稱、首頁標題、介紹和 About 內容。再檢查一篇有譯文的文章、一篇沒有譯文的文章,確認語言切換符合預期。語言列表和檔案目錄代碼要完全一致。

發佈前停止 dev,執行:

npm run doctor
npm run preview

doctor 包含檢查和建置,成功後不必立即再執行 check 或 build。用建置後的 preview 驗證各語言文章搜尋;索引搜尋目前語言,不會把全部語言混在一起。每種已啟用語言的 RSS 位於 /<locale>/rss.xml,只包含相應語言的文章。

確認網站網域正確後,重新部署整個 dist/。語言啟停、預設地址和內容變化都需要重新建置;僅修改本機設定不會改變線上頁面。重新部署要注意清理舊產物,關閉語言不是為舊網址自動建立重新導向。

現象 先檢查什麼
選單仍顯示不需要的語言 是否只是從設定刪掉了覆寫項,而沒有明確設定 enabled: false
預設語言無法關閉 是否仍將它設為 defaultLocale;先選擇新的預設語言
建立了檔案卻沒有頁面 語言是否啟用,目錄代碼是否一致,是否已經重新建置
頁面還有英文 新語言是否只覆寫了部分文字,或缺少對應 About 內容
改了標題卻沒有變 改的是全站 site.title、首頁 homeTitle、hero,還是頁面 messages;檢查環境覆寫值
切語言後進入列表 目標語言是否缺少同 slug 譯文,這屬於目前回退行為
設定 never 後文章仍有語言前綴 此開關只改變預設語言首頁,這是預期行為

網站資訊和升級步驟見安裝教學,日常寫作見寫第一篇文章。

教學導覽與設定查閱

上一篇:讓讀者留下評論 · 下一篇:把部落格發佈到自己的網域 · 八篇教學總入口。

本篇相關欄位:語言、地址與回退、跨語言評論共享。完整路徑、預設值和限制見設定字典總入口。