vue-i18n：Vue3中實現國際化(i18n)的完整方案與最佳實踐詳情 - 多語言,初始化,API,Vue.js,前端開發子丶不語博客

隨着前端項目的業務邊界不斷擴大，“國際化”早已不是可選功能，而是面向全球用户的必備能力。對於Vue3項目而言，vue-i18n作為官方推薦的國際化解決方案，以其輕量、靈活、易集成的特點，成為眾多開發者的首選。今天就帶大家從0到1掌握vue-i18n，輕鬆搞定多語言適配！

一、為什麼Vue3項目要選vue-i18n？

在聊具體用法前，先明確一個問題：市面上國際化插件不少，為什麼vue-i18n能脱穎而出？核心原因在於它與Vue生態的“原生契合度”。

作為Vue官方維護的國際化庫，vue-i18n完美適配Vue3的Composition API，支持Teleport、 Suspense等新特性，還能與Vuex/Pinia、Vue Router等生態工具無縫銜接。此外，它還提供了豐富的功能：

簡潔的語法：模板和JS中都能輕鬆調用多語言文案
動態切換：無需刷新頁面即可實時切換語言
佔位符與格式化：支持數字、日期等數據的多語言格式化
兼容性強：適配Vue2和Vue3，遷移成本低

對於Vue3項目來説，選擇vue-i18n就意味着“少踩坑、高兼容、易維護”，這也是它成為主流方案的關鍵。

二、從安裝到配置，3步完成初始化

vue-i18n的初始化流程非常清晰，無論是Vite還是Webpack構建的Vue3項目，都能快速上手。我們以 Vite+Vue3項目為例，一步步操作。

第一步：安裝依賴 Vue3項目需要安裝vue-i18n的最新版本（當前穩定版為v9+），直接通過npm或yarn安裝：

# npm
npm install vue-i18n@next --save
# yarn
yarn add vue-i18n@next --save

這裏的@next指定安裝適配Vue3的版本，避免安裝到Vue2兼容版。

第二步：創建多語言配置文件

在src目錄下新建lang文件夾，用於存放不同語言的配置文件。通常我們會創建中文（zh-CN.js）和英文（en-US.js）兩個基礎文件，後續可根據需求擴展其他語言。

▌src/lang/zh-CN.js（中文配置）

export default {
  common: {
    welcome: '歡迎使用Vue3國際化方案',
    switchLang: '切換語言',
    confirm: '確認',
    cancel: '取消'
  },
  user: {
    login: '登錄',
    register: '註冊',
    username: '用户名',
    password: '密碼'
  }
}

▌src/lang/en-US.js（英文配置）

export default {
  common: {
    welcome: 'Welcome to Vue3 Internationalization Solution',
    switchLang: 'Switch Language',
    confirm: 'Confirm',
    cancel: 'Cancel'
  },
  user: {
    login: 'Login',
    register: 'Register',
    username: 'Username',
    password: 'Password'
  }
}

配置文件採用鍵值對形式，建議按業務模塊（如common、user）劃分，方便後續維護。

第三步：初始化i18n實例並掛載

在lang文件夾下新建index.js，用於創建i18n實例並配置基礎參數：

import { createI18n } from 'vue-i18n'
// 導入語言配置文件
import zhCN from './zh-CN'
import enUS from './en-US'
// 定義語言庫
const messages = {
  'zh-CN': zhCN,
  'en-US': enUS
}
// 檢測瀏覽器默認語言（可選）
const getDefaultLanguage = () => {
  const navLang = navigator.language
  if (messages[navLang]) {
    return navLang
  }
  // 默認返回中文
  return 'zh-CN'
}
// 創建i18n實例
const i18n = createI18n({
  // 採用Composition API模式
  legacy: false,
  // 全局注入$t方法
  globalInjection: true,
  // 默認語言
  locale: getDefaultLanguage(),
  // 語言庫
  messages
})
export default i18n

這裏有兩個關鍵參數需要注意：

legacy: false：開啓Composition API模式，必須設置為false才能在Vue3的setup中正常使用
globalInjection: true：全局注入$t方法，這樣在模板中無需導入即可直接使用

最後在main.js中掛載i18n實例：

import { createApp } from 'vue'
import App from './App.vue'
import i18n from './lang'
const app = createApp(App)
// 掛載i18n
app.use(i18n)
app.mount('#app')

至此，vue-i18n的初始化工作就完成了，接下來就能在項目中使用多語言功能了。

三、核心用法：模板與JS中調用多語言

vue-i18n提供了簡潔的調用方式，無論是模板還是JS/TS代碼中，都能輕鬆獲取多語言文案。

1. 模板中使用$t方法

由於開啓了globalInjection，模板中可直接通過$t('鍵名')調用對應文案，鍵名對應配置文件中的層級結構：

<template>
  <div class="international-demo">
    <h1>{{ $t('common.welcome') }}</h1>
    <form class="user-form">
      <label>{{ $t('user.username') }}：</label>
      <input type="text" placeholder="{{ $t('user.username') }}">


      <label>{{ $t('user.password') }}：</label>
      <input type="password" placeholder="{{ $t('user.password') }}">


      <button>{{ $t('user.login') }}</button>
      <button>{{ $t('user.register') }}</button>
    </form>
  </div>
</template>

2. JS/TS中調用（Composition API）

在setup語法糖中，需要通過useI18n鈎子獲取t方法，這也是Composition API的標準用法：

<script setup>
import { useI18n } from 'vue-i18n'
// 獲取t方法和當前語言
const { t, locale } = useI18n()
// 在邏輯中使用多語言
const handleLogin = () => {
  alert(t('user.login') + ' ' + t('common.success')) // 拼接多語言文案
}
</script>

3. 帶佔位符的多語言文案

實際開發中，經常需要在文案中插入動態數據（如用户名、數量等），此時可在配置文件中使用佔位符，調用時傳入參數：

▌修改zh-CN.js：

export default {
  common: {
    // 佔位符用{ }表示
    welcomeWithName: '歡迎您，{name}！您今天有{count}條消息'
  }
}

▌調用時傳入參數：

<template>
  <p>{{ $t('common.welcomeWithName', { name: '張三', count: 3 }) }}</p>
</template>
<script setup>
import { useI18n } from 'vue-i18n'
const { t } = useI18n()
// JS中調用
const message = t('common.welcomeWithName', { name: '張三', count: 3 })
</script>

四、進階功能：動態切換語言與數據格式化

除了基礎的文案調用，vue-i18n還支持動態切換語言、日期/數字格式化等實用功能，滿足複雜場景需求。

1. 動態切換語言

切換語言的核心是修改i18n實例的locale屬性，結合UI組件即可實現語言切換按鈕的功能：

<template>
  <div class="lang-switch">
    <button @click="switchLang('zh-CN')" :class="{ active: locale === 'zh-CN' }">中文</button>
    <button @click="switchLang('en-US')" :class="{ active: locale === 'en-US' }">English</button>
  </div>
</template>
<script setup>
import { useI18n } from 'vue-i18n'
const { locale } = useI18n()
// 切換語言方法
const switchLang = (lang) => {
  locale.value = lang
  // 可選：將語言存入localStorage，下次打開保持狀態
  localStorage.setItem('defaultLang', lang)
}
// 初始化時從localStorage讀取語言（優化體驗）
onMounted(() => {
  const savedLang = localStorage.getItem('defaultLang')
  if (savedLang) {
    locale.value = savedLang
  }
})
</script>

通過localStorage存儲語言偏好，能讓用户下次打開頁面時保持上次選擇的語言，提升用户體驗。

2. 日期與數字格式化

不同語言區域的日期、數字格式存在差異（如中文用“年/月/日”，英文用“月/日/年”），vue-i18n提供了$d（日期格式化）和$n（數字格式化）方法：

<template>
  <div class="format-demo">
    <p>{{ $t('common.currentDate') }}：{{ $d(new Date(), 'long') }}</p>
    <p>{{ $t('common.amount') }}：{{ $n(12345.67, 'currency') }}</p>
  </div>
</template>

需要在i18n初始化時配置格式化規則，具體可參考vue-i18n官方文檔的“格式化”章節，根據業務需求自定義格式。

五、避坑指南：這些問題要注意

在使用vue-i18n的過程中，新手容易遇到一些細節問題，這裏整理了常見坑點及解決方案：

坑點1：setup中無法使用$t → 原因是未開啓globalInjection，或未通過useI18n獲取t方法，需檢查i18n配置中的globalInjection是否為true，setup中必須用useI18n。
坑點2：切換語言後部分文案不更新 → 確保文案都是通過$t或t方法調用，而非硬編碼；如果是在Pinia/Vuex中使用，需確保狀態更新時觸發組件重新渲染。
坑點3：瀏覽器默認語言識別錯誤 → 部分瀏覽器返回的navigator.language是“zh”而非“zh-CN”，可在getDefaultLanguage方法中增加判斷，如將“zh”映射為“zh-CN”。

六、總結：vue-i18n的核心優勢

作為Vue3生態的官方國際化方案，vue-i18n的核心優勢在於“輕量、適配、易擴展”：

1. 與Vue3 Composition API深度契合，開發體驗統一；

2. 配置簡單，從安裝到使用僅需3步，新手易上手；

3. 功能全面，支持動態切換、數據格式化等複雜需求；

4. 官方維護，兼容性和穩定性有保障。

如果你的Vue3項目正在做國際化適配，vue-i18n絕對是值得優先選擇的方案。按照本文的步驟操作，相信你能快速搞定多語言功能，讓項目輕鬆面向全球。

子丶不語博客

子丶不語博客

博客 / 詳情