Skip to content
• Anonymous

i18n 多國語系動態路由：[lang] 架構與 SSG 預渲染的技術細節

深入解析 DueWise 如何實現優雅的多語系支持，包括動態路由、語系偵測、SSG 高性能生成以及 SEO 友善的 hreflang 配置。

#i18n #Astro #Dynamic Routing #SEO #SSG

i18n 多國語系動態路由：[lang] 架構與 SSG 預渲染的技術細節

在當前的全球化市場中，提供多語系支援已不再是選配，而是標配。對於 DueWise 這樣一款希望能幫助全球用戶管理效期的應用程式，我們實作了一套基於 Astro 的高效多語系 (i18n) 系統。

這套系統不僅要能切換文字，更要兼顧 SEO (搜尋引擎優化)、AEO (AI 搜尋優化) 以及 加載效能。

1. 語系資料管理：中心化的翻譯檔

我們並未選用複雜的 i18next 或類似庫，而是採用了 TypeScript 原生物件管理翻譯。在 src/i18n.ts 中，我們定義了嚴謹的類型約束：

export type Locale = 'en' | 'zh-TW' | 'ja' | 'ko';

export const translations: Record<Locale, any> = {
  'en': { common: { welcome: 'Welcome' }, ... },
  'zh-TW': { common: { welcome: '歡迎' }, ... },
  // 其他語系...
};

使用 TypeScript 的好處是：當我們在 common 中新增一個鍵（Key）時，編譯器會立刻提醒我們其他語系尚未補齊。

2. 路由設計：動態路由 [lang]

Astro 的檔案路由系統非常強大。我們使用了 src/pages/[lang]/index.astro 這種動態路由設計。

getStaticPaths 的力量

為了保證首頁在所有語言下都能「秒開」，我們啟用了 SSG (Static Site Generation)：

export function getStaticPaths() {
  return [
    { params: { lang: 'en' } },
    { params: { lang: 'ja' } },
    { params: { lang: 'ko' } },
    { params: { lang: 'zh-TW' } },
  ];
}

這意味著當我們執行 npm run build 時，Astro 會預先產生 /en/index.html、/ja/index.html 等頁面。這種做法讓伺服器完全不需要進行運算，直接由 Cloudflare 邊緣節點供應 HTML。

3. SEO 與 AEO 的關鍵：hreflang 與 Canonical

多語系網站最怕被 Google 判定為「重複內容」。我們在 Layout.astro 中實作了動態的 Meta 標籤生成：

<!-- Hreflang 告訴 Google 這些頁面是互為翻譯的 -->
<link rel="alternate" hreflang="zh-TW" href="https://duewise.cc/" />
<link rel="alternate" hreflang="en" href="https://duewise.cc/en/" />
<link rel="alternate" hreflang="x-default" href="https://duewise.cc/" />

此外，我們還在頁面中注入了對應語系的 JSON-LD 結構化資料，這讓 ChatGPT 或 Perplexity 這樣的 AI 搜尋引擎能更精確地理解 DueWise 在不同語境下的功能。

4. 語系偵測與自動重新導向

當使用者訪問根目錄 https://duewise.cc/ 時，我們如何知道他偏好哪種語言？

由於我們使用了 SSG，我們無法在伺服器端做動態過濾。但在 DueWise 中，我們採用了混合策略：

  • 預設顯示: 根據地理位置或預設（目前為繁中）。
  • 語系切換器: 在 UI 上提供顯眼的切換按鈕。
  • 持久化記憶: 當使用者切換語系後，我們會將其存入 localStorage 與 Cookie，下次開啟 App 時自動對接到正確路由。

5. 開發體驗的技術細節

在代碼層面，我們封裝了一個簡單的 Helper：

// 快速取得目前語系的路徑
const getPath = (path: string) => currentLang === 'zh-TW' ? path : `/${currentLang}${path}`;

// 使用範例
<a href={getPath('/privacy')}>隱私權</a>

這種做法避免了在組件中硬編碼 (Hardcode) URL 的問題，讓未來的路徑重構變得非常容易。

個人心得：這值得嗎？

實作完整的多語系動態路由確實會增加一些開發負擔，特別是在處理第三方認證（OAuth）的回調路徑時。然而，當你看到來自日本或韓國的用戶開始在社交媒體上分享你的 App，且他們看到的介面是熟悉的母語時，這一切努力都得到了回報。

更重要的是，這套架構讓 DueWise 的搜尋曝光率提升了數倍，比起單一語系的網站，它擁有了全球競爭力。

結論

i18n 不只是翻譯文字，它是一門關於路由、SEO 與使用者心理學的綜合藝術。透過 Astro 的 [lang] 動態路由與 SSG，我們建立了一個既全球化又高性能的 PWA 標竿。

下一篇文章，我們將深入離線技術的核心：「打造離線優先 (Offline-First) 應用：IndexedDB 與資料同步機制的設計」。