Skip to main content

Vue i18n：使用 vue-i18n 的國際化完整設定

從安裝到生產環境：通過 Composition API 設定 vue-i18n、使用 CLDR 規則處理複數、使用元件插值，並新增智能地區設定回退鏈。

1

安裝 vue-i18n

vue-i18n 是 Vue.js 的官方國際化外掛程式。它提供響應式翻譯、ICU 風格複數、元件插值、日期時間和數字格式化，並同時支援 Options API 和 Composition API。

Terminal
npm install vue-i18n@9
2

設定 vue-i18n

使用 createI18n() 建立 i18n 實例，並將其註冊為 Vue 外掛程式。定義地區設定訊息、設定預設地區設定並設定回退地區設定。vue-i18n 同時支援 legacy（Options API）和 composition（Composition API）模式。

src/i18n.ts
// src/i18n.ts
import { createI18n } from 'vue-i18n'
import en from './locales/en.json'
import de from './locales/de.json'

const i18n = createI18n({
  legacy: false,           // Use Composition API mode
  locale: 'en',            // Default locale
  fallbackLocale: 'en',   // Fallback locale
  messages: { en, de },
})

export default i18n
src/main.ts
// src/main.ts
import { createApp } from 'vue'
import App from './App.vue'
import i18n from './i18n'

const app = createApp(App)
app.use(i18n)
app.mount('#app')
如果看到 'Not available in legacy mode' 錯誤，說明你混用了 Composition API i18n 呼叫（useI18n()）和 legacy 模式設定。請在 createI18n() 中設定 legacy: false 以使用 Composition API 模式，或始終使用 Options API 的 $t() 語法。
3

在範本中使用翻譯

vue-i18n 在範本中提供 $t() 函數（Options API），並通過 useI18n() 提供 t() 函數（Composition API）。兩者都接收翻譯鍵以及用於插值的可選命名參數或列表參數。

src/locales/en.json
// src/locales/en.json
{
  "nav": {
    "home": "Home",
    "about": "About",
    "settings": "Settings"
  },
  "greeting": "Hello, {name}!",
  "cart": {
    "itemCount": "no items | one item | {count} items"
  }
}

// src/locales/de.json
{
  "nav": {
    "home": "Startseite",
    "about": "Über uns",
    "settings": "Einstellungen"
  },
  "greeting": "Hallo, {name}!",
  "cart": {
    "itemCount": "keine Artikel | ein Artikel | {count} Artikel"
  }
}
4

處理複數

vue-i18n 通過豎線分隔的形式和 $tc() 函數（legacy），或帶 count 參數的 t()（Composition API）支援複數。在地區設定訊息中使用豎線分隔符定義複數形式：'沒有項目 | 一個項目 | {count} 個項目'。

MyComponent.vue
<template>
  <div>
    <!-- Simple translation -->
    <h1>{{ $t('nav.home') }}</h1>

    <!-- With variables -->
    <p>{{ $t('greeting', { name: userName }) }}</p>

    <!-- In attributes -->
    <input :placeholder="$t('nav.settings')" />

    <!-- Composition API -->
    <p>{{ greeting }}</p>
  </div>
</template>

<script setup lang="ts">
import { useI18n } from 'vue-i18n'

const { t } = useI18n()
const userName = 'Alice'
const greeting = t('greeting', { name: userName })
</script>
豎線分隔的複數語法僅支援最多三種基數複數形式（zero | one | other）。對於具有複雜 CLDR 複數規則的語言（阿拉伯語、俄語、波蘭語），請使用 ICU MessageFormat 語法或帶顯式 CLDR 類別對應的 @.plural 修飾符。
5

新增地區設定回退鏈

vue-i18n 內置的 fallbackLocale 僅支援扁平回退地區設定列表，不支援針對每個地區設定的鏈。缺少某個鍵時，pt-BR 用戶會回退到英語，而不是 pt-PT。vue-i18n-locale-chain 新增可設定的深度合併鏈，使地區用戶始終看到最接近的可用翻譯。

Plurals.vue
<template>
  <div>
    <!-- Pipe-separated plurals -->
    <p>{{ $t('cart.itemCount', count) }}</p>

    <!-- Named plurals (recommended for complex languages) -->
    <p>{{ $t('orders', { n: orderCount }) }}</p>
  </div>
</template>

<!-- In your locale file: -->
<!-- "orders": "{n} order | {n} orders" -->
vue-i18n-locale-chain 在載入時深度合併訊息。合併後的訊息集由 vue-i18n 的響應式系統快取，因此回退查找不會帶來執行階段性能損失。
6

自動翻譯

設定 vue-i18n 後，使用 AI 翻譯地區設定 JSON 檔案。從 IDE 讓 AI 助手翻譯來源檔案，或將翻譯整合到 CI/CD 管線，實現完全自動化的本地化。

LanguageSwitcher.vue
<template>
  <select v-model="locale">
    <option v-for="lang in availableLocales" :key="lang" :value="lang">
      {{ lang }}
    </option>
  </select>
</template>

<script setup lang="ts">
import { useI18n } from 'vue-i18n'

const { locale, availableLocales } = useI18n()
</script>
src/i18n.ts (lazy loading)
// src/i18n.ts
import { createI18n } from 'vue-i18n'

const i18n = createI18n({
  legacy: false,
  locale: 'en',
  fallbackLocale: 'en',
  messages: {},
})

export async function loadLocale(locale: string) {
  const messages = await import(`./locales/${locale}.json`)
  i18n.global.setLocaleMessage(locale, messages.default)
  i18n.global.locale.value = locale
}

export default i18n
7

地區設定回退鏈設定

為每個地區設定回退鏈，使地區用戶看到最接近的可用翻譯，而不是直接跳到英語。vue-i18n 支援使用物件形式的 fallbackLocale 為每個地區設定定義回退鏈。

src/i18n.ts
// src/i18n.ts
import { createI18n } from 'vue-i18n'

const i18n = createI18n({
  legacy: false,
  locale: 'pt-BR',
  fallbackLocale: {
    'pt-BR': ['pt', 'en'],
    'zh-Hant-TW': ['zh-Hant', 'zh', 'en'],
    'es-419': ['es', 'en'],
    default: ['en'],
  },
  messages: {
    en: { /* ... */ },
    pt: { /* ... */ },
    'pt-BR': { /* ... */ },
  },
})
fallbackLocale 物件允許為不同地區設定定義不同回退鏈。pt-BR 用戶依次回退到 pt 和 en，zh-Hant-TW 用戶則依次回退到 zh-Hant、zh 和 en。

常見問題

混用 Legacy 與 Composition API 模式

在 legacy: true（預設值）時使用 useI18n() 會導致錯誤。如果使用 Composition API，請在 createI18n() 中設定 legacy: false；如果使用 Options API，則堅持在範本中使用 $t()。請勿在同一應用程式中混用兩種模式。

對翻譯字串使用 v-html

如果任何插值值來自用戶輸入，使用 v-html 呈現包含 HTML 的翻譯會帶來 XSS 風險。對於嵌入 HTML 或 Vue 元件的翻譯，請使用 &lt;i18n-t&gt; 元件，它預設安全，並支援嵌入響應式元件。

區域用戶看到英語而非父語言

vue-i18n 的 fallbackLocale 是扁平列表，不是針對每個地區設定的鏈。pt-BR 會回退到列表中的值（通常是 'en'），並完全跳過 pt-PT。使用 vue-i18n-locale-chain 通過深度合併新增正確的地區回退。

立即試用 i18n Agent

將翻譯檔案拖放到此處

JSON, YAML, PO, XML, CSV, Markdown, Properties

或點擊選擇檔案

目標語言

無需註冊即時估價

Vue i18n 常見問題