ALL NOTES

LAB NOTES / 2026.10.21

語系切換|使用 data-i18n 實現多國語系的流暢切換

在開發網站時,如果希望網頁能夠同時支援多種語言切換,最經典的做法之一就是使用 data-i18n 屬性。

「i18n」代表 Internationalization(國際化) – 因為這個單字開頭是 i、結尾是 n,中間剛好有 18 個字母,所以簡稱為 i18n。覺得想出這個方式的人也是蠻幽默的,那 hippopotomonstrosesquippedaliophobia 應該也可以縮寫成 「h34a」(離題)。

(hippopotomonstrosesquippedaliophobia:對長單字的恐懼。)

回來繼續講 data-i18n, 它是 HTML5 規範中專門用來替元素標記「這段文字需要進行多國語系翻譯」的自訂資料屬性。


當初在規劃功能時,本來以為「多語系切換」應該跟實現「深淺色模式(Dark/Light Mode)」的方式差不多–只要寫好兩組對應的變數或樣式,切換個按鈕就能搞定。

但實際動手做之後,發現裡面其實有很多需要注意的眉眉角角。

首先,光是要實現多語系的方法就有好幾種,像是為不同語言建立專屬的網址路徑、甚至是獨立子網域等。不過因為我目前的專案都是比較小型的作品,最後我主要用 data-i18n 的方式。


data-i18n 是如何運作的?

它的核心概念是 把 HTML 結構裡的固定文字抽離,換成一個「翻譯對應的 Key」,然後透過 JavaScript 搭配語系字典檔來動態替換。

1. HTML 結構範例

在寫網頁標籤時,加上 data-i18n 屬性:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
<header>
<!-- 導覽列按鈕 -->
<nav>
<a href="#home" data-i18n="navHome">首頁</a>
<a href="#about" data-i18n="navAbout">關於我</a>
<a href="#projects" data-i18n="navProjects">作品集</a>
</nav>
</header>

<main>
<!-- 頁面標題 -->
<h1 data-i18n="heroTitle">歡迎來到我的網站</h1>

<!-- 按鈕 -->
<button id="submit-btn" data-i18n="btnSubmit">送出表單</button>
</main>

2. 準備語系字典檔(JSON 格式)

搭配我們 前面 提過的 JSON 格式,建立不同語言的對照字典(這邊用扁平結構示範):

zh-TW.json

1
2
3
4
5
6
7
{
"navHome": "首頁",
"navAbout": "關於我",
"navProjects": "作品集",
"heroTitle": "歡迎來到我的網站",
"btnSubmit": "送出表單"
}

en.json

1
2
3
4
5
6
7
{
"navHome": "Home",
"navAbout": "About Me",
"navProjects": "Projects",
"heroTitle": "Welcome to My Website",
"btnSubmit": "Submit"
}

3. JavaScript 切換語系

當點擊切換語言的按鈕時,JavaScript 會做三件事:

  1. 讀取對應語系的 JSON 檔案。

  2. 找出網頁上所有帶有 data-i18n 屬性的元素。

  3. 根據屬性裡的值(例如 navHome),去 JSON 字典中找到對應的文字,並填入網頁中。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// 假設載入進來的翻譯資料叫 translations
function switchLanguage(translations) {
// 找出所有帶有 data-i18n 的元素
const elements = document.querySelectorAll('[data-i18n]');

elements.forEach(el => {
const key = el.getAttribute('data-i18n'); // 例如拿到 "navHome"
const text = translations[key];

if (text) {
el.textContent = text; // 替換畫面上的文字
}
});
}

使用 data-i18n 有什麼優點?

  1. 結構與內容分離:前端排版(HTML)不用管現在到底是中文還是英文,程式碼保持乾淨清爽。

  2. 擴充性高:未來如果想要新增韓文、法文,只需要多寫一個 ko.json 或 fr.json 檔案,完全不需要修改原本的 HTML 結構。

  3. 維護方便:如果需要修改錯別字,直接修改 JSON 字典檔就好,不用在 HTML 檔案中找。


實作中我遇到的問題與解決辦法

1. 字典結構的選擇:扁平 vs. 巢狀

當初在規劃 JSON 字典檔時,直覺選擇了最簡單的扁平結構。然而,當專案的頁面與元件越來越多時,開始覺得當初若採用巢狀結構,整體的分類與可讀性應該會清晰許多。

如果預期專案未來可能會擴展、變得比較複雜,確實可以考慮一開始就使用巢狀結構來分類;不過相對地,JavaScript 在解析時就需要寫比較複雜的遞迴函式來層層取值。建議可以根據專案的規模來評估與斟酌。

扁平結構範例
寫起來很直覺,所有的 key 都攤平在同一層。

1
2
3
4
{
"navHome": "首頁",
"navAbout": "關於我",
}

*巢狀結構範例**

1
2
3
4
5
6
{
"nav": {
"home": "首頁",
"about": "關於我"
}
}

2.data-i18n 的 Key 命名限制

一開始在寫 data-i18n 的屬性值時,習慣性地用了連字號(例如 -),寫成data-i18n="nav-home"。
結果在 JavaScript 透過點記法解析時,一直報錯,因為在 JS 裡 - 會被誤認為是 「減號」,導致程式無法正確讀取屬性。後來改用 小駝峰命名法,問題才順利解決。

3. 段落換行

有時候網頁上的 <p> 段落文字比較長,會需要換行排版。如果直接在 JSON 字典的字串裡塞入 HTML 標籤(例如 "intro": "第一行<br>第二行"),畫面會直接把 <br> 字串當成純文字印出來,完全沒有達到換行的效果;後來遇到需要排版、斷行比較複雜的段落文字,我會避免全部塞在同一個 JSON 欄位裡,直接拆分。


補充:除了 data-i18n 之外,多語系還有哪些常見方式?

除了 data-i18n 之外,在實際開發中,根據專案的規模與需求,還有以下幾種常見的實作方式:

1. 路由分流法(Localized Routing / URL Path)—— SEO 友善首選

為不同的語言建立專屬的網址路徑(例如 /zh-TW/about、/en/about)。搜尋引擎可以明確索引每一個語言的獨立頁面,適合企業官網。

2. 獨立子網域法(Subdomain Routing)

透過不同的子網域來區隔語系(例如 zh.example.com 與 en.example.com),適合跨國大企業或不同市場營運邏輯差異較大的網站。

3. 前端狀態切換法(State-based Language Switcher)

網址維持不變,透過前端 JavaScript 的狀態管理在單頁式應用(SPA)中動態抽換畫面文字,開發結構簡單,適合小型個人網站或作品集。

4. 瀏覽器自動偵測與重新導向

透過 JavaScript 讀取瀏覽器的預設語系(navigator.language),自動將網站切換到對應語言,通常會搭配 localStorage 記錄使用者的選擇。

5. 第三方翻譯外掛(自動機器翻譯)

引入 Google 翻譯外掛或 SaaS 服務,免手動維護字典檔,幾秒鐘就能讓網站支援數十種語言,適合急需多語系但無人力翻譯的小型資訊網站。

所有筆記