Vue i18n 多語系網站開發實作 — 從設定到維護的經驗分享
從航運公司中英文網站的經驗,整理 Vue i18n 的註冊、語言切換、插值、複數與日期格式,也留意翻譯檔案和多語系 SEO。
本篇目錄
之前做過一個航運公司的企業形象網站,需要支援中英文切換。以下整理使用 Vue i18n 的設定方式,以及開發和維護多語系網站時遇到的問題。
為什麼需要多語系
如果網站面向不同國家的客群,或公司有海外業務,就需要讓使用者用熟悉的語言閱讀內容。多語系支援能減少理解上的障礙,也有助於呈現公司的國際業務形象。
Vue i18n 基本設定
Vue i18n 是 Vue 常用的多語系套件。下面以 Vue 3、Vue i18n 11 的 Composition API 模式為例;Nuxt 搭配 @nuxtjs/i18n 時,則應依模組設定整合,不必再照純 Vue 專案的入口註冊方式做一次。
在 Vue 3 專案中安裝 vue-i18n@11,先建立 i18n instance:
// i18n/index.js
import { createI18n } from "vue-i18n";
import zhTW from "../locales/zh-TW.json";
import en from "../locales/en.json";
const i18n = createI18n({
legacy: false,
globalInjection: true,
locale: "zh-TW",
fallbackLocale: "en",
messages: {
"zh-TW": zhTW,
en: en,
},
});
export default i18n;
這份檔案放在 src/i18n/index.js,翻譯檔案則放在 src/locales/。還要在入口 src/main.js 把 instance 註冊到 app,元件裡才有 $t 與 useI18n 可用:
// main.js
import { createApp } from "vue";
import App from "./App.vue";
import i18n from "./i18n";
createApp(App).use(i18n).mount("#app");
註冊必須在 mount 之前完成,順序可對照官方入門文件。
翻譯檔案就是一般的 JSON。下方先列中文內容,英文檔也要準備相同 key 的翻譯。JSON 本身不接受註解,所以頂端用來標示檔案位置的註解,實際存檔時要移除,後面的翻譯範例也一樣。
// locales/zh-TW.json
{
"nav": {
"home": "首頁",
"about": "關於我們",
"services": "服務項目",
"contact": "聯絡我們"
},
"home": {
"title": "歡迎來到我們的網站",
"description": "專業的國際航運服務"
}
}
在元件中使用
在 template 裡面用 $t() 來取得翻譯文字:
<template>
<nav>
<a href="/">{{ $t("nav.home") }}</a>
<a href="/about">{{ $t("nav.about") }}</a>
</nav>
</template>
在 script 裡面則用 useI18n:
<script setup>
import { useI18n } from "vue-i18n";
const { t, locale } = useI18n();
const switchLanguage = (lang) => {
locale.value = lang;
};
</script>
(純 Vue 專案預設沒有 auto-import,useI18n 要自己 import;如果另外裝了 unplugin-auto-import,並在 imports 設定加入 vue-i18n preset,或是 Nuxt 搭配 @nuxtjs/i18n,這行就可以省略。)
語言切換的 UI
使用者要能切換語言,通常會在 header 放一個語言選擇器。下面 template 的 locale 沿用前一段 useI18n 取得的值:
<template>
<select v-model="locale">
<option value="zh-TW">中文</option>
<option value="en">English</option>
</select>
</template>
如果用上面的 v-model 選擇器直接修改 locale,語言會切換,但不會自動執行 switchLanguage。要記住使用者的選擇,可以讓選擇器的 change handler 呼叫這個函式,或 watch 語言值再保存到 localStorage。以下先示範函式內的處理:
// 切換語言時
const switchLanguage = (lang) => {
locale.value = lang;
localStorage.setItem("locale", lang);
};
// 初始化時讀取
const savedLocale = localStorage.getItem("locale");
if (savedLocale) {
locale.value = savedLocale;
}
這段只適用於瀏覽器端,讀取後還要檢查保存的值是否為支援的語系,例如 zh-TW 或 en。若放進 Nuxt 的 SSR 流程,讀取 localStorage 前要確認是在客戶端,還要處理伺服器與瀏覽器初始語言不同時的畫面同步。
翻譯檔案的管理
專案變大後,可以再整理翻譯檔案:
拆分檔案
不要把所有翻譯都塞在一個 JSON 裡面,按功能或頁面拆分:
locales/
zh-TW/
common.json
home.json
about.json
en/
common.json
home.json
about.json
命名規則要一致
key 的命名最好有規則可循,例如 頁面.區塊.元素。這樣找翻譯的時候比較快,也比較不會重複。
避免太深的巢狀
巢狀太深會讓 key 變得很長,寫起來麻煩,也不好維護。通常三層以內比較適當。
處理複數和變數
有些文字會包含變數,或是需要處理複數形式:
// locales/zh-TW.json
{
"items": {
"count": "共 {count} 個項目"
}
}
<p>{{ $t('items.count', { count: 5 }) }}</p>
<!-- 輸出:共 5 個項目 -->
英文的複數比較麻煩,好在 Vue i18n 有內建處理:
// locales/en.json(同一個 items.count key,換成 en 語系的複數寫法)
{
"items": {
"count": "no items | one item | {count} items"
}
}
切換到 en 後,同樣呼叫 $t('items.count', { count: 5 }),會選到第三段而顯示 5 items。這裡的 count 同時用來插值與選擇複數形式。
日期和數字格式
不同語系的日期和數字格式也不一樣。日期可在原本的 createI18n 設定中加入 datetimeFormats,不要另外建立一個沒有註冊的新 instance:
const i18n = createI18n({
// ...
datetimeFormats: {
"zh-TW": {
short: { year: "numeric", month: "2-digit", day: "2-digit" },
},
en: {
short: { year: "numeric", month: "short", day: "numeric" },
},
},
});
<p>{{ $d(new Date(), 'short') }}</p>
<!-- zh-TW: 2025/03/15 -->
<!-- en: Mar 15, 2025 -->
註解只是以 2025 年 3 月 15 日為例;new Date() 實際輸出的是執行當天的日期,格式也可能受執行環境的 locale 資料影響。
SEO 注意事項
多語系網站的 SEO 有些要注意的地方:
設定 lang 屬性
HTML 標籤要加上正確的語言屬性:
<html lang="zh-TW"></html>
切換語言時也要更新這個屬性。
hreflang 標籤
告訴搜尋引擎這個頁面有其他語言版本。前提是每個語言版本都有自己的網址,例如下面的 /zh-TW/about 和 /en/about;每個版本的頁面都要放上同一組標籤,列出所有語言版本,包含自己:
<link rel="alternate" hreflang="zh-TW" href="https://example.com/zh-TW/about" />
<link rel="alternate" hreflang="en" href="https://example.com/en/about" />
前面的語言切換只改 locale,再存進 localStorage,網址不會變。爬蟲抓頁面時沒有使用者存下的語言設定,在同一個網址上通常只會看到預設語言。要做多語系 SEO,語系要改由路由決定,例如在 Vue Router 的路徑前面加上 /:locale,或使用 @nuxtjs/i18n 的 prefix、prefix_except_default 策略,讓 locale 跟著網址同步。localStorage 只用來記住使用者上次選的語言。
實務經驗
做過多語系專案後,有些經驗可以分享:
-
一開始就規劃好:後期才加多語系會很痛苦,一開始就用
$t()來寫,後面加語言就輕鬆很多 -
翻譯內容需要語言校對:重要文字可以請專業翻譯人員或熟悉該語言的人確認,工程端則處理載入、插值和顯示方式
-
測試每個語系:切換到其他語言後,版面可能會跑掉,因為不同語言的文字長度不一樣。英文和中文的長度差異尤其大
-
圖片也要處理:如果圖片上有文字,也需要準備不同語言的版本
站內相關文章: