Skip to main content

Vue i18n: Penyiapan Internasionalisasi Lengkap dengan vue-i18n

Dari instalasi hingga produksi: konfigurasikan vue-i18n dengan Composition API, tangani bentuk jamak dengan aturan CLDR, gunakan interpolasi komponen, dan tambahkan rantai fallback locale cerdas.

1

Instal vue-i18n

vue-i18n adalah plugin internasionalisasi resmi untuk Vue.js. Plugin ini menyediakan terjemahan reaktif, bentuk jamak bergaya ICU, interpolasi komponen, pemformatan tanggal/waktu dan angka, serta dukungan Options API dan Composition API.

Terminal
npm install vue-i18n@9
2

Konfigurasikan vue-i18n

Buat instance i18n dengan createI18n() dan daftarkan sebagai plugin Vue. Tentukan pesan locale, atur locale default, dan konfigurasikan locale fallback. vue-i18n mendukung mode legacy (Options API) dan 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')
Jika Anda melihat kesalahan 'Not available in legacy mode', Anda mencampurkan panggilan i18n Composition API (useI18n()) dengan konfigurasi mode legacy. Atur legacy: false dalam createI18n() untuk menggunakan mode Composition API, atau gunakan sintaks $t() Options API secara konsisten.
3

Gunakan Terjemahan dalam Template

vue-i18n menyediakan fungsi $t() dalam template (Options API) dan fungsi t() dari useI18n() (Composition API). Keduanya menerima kunci terjemahan dan parameter bernama/daftar opsional untuk interpolasi.

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

Tangani Bentuk Jamak

vue-i18n mendukung bentuk jamak melalui bentuk yang dipisahkan tanda pipa dan fungsi $tc() (legacy) atau t() dengan parameter count (Composition API). Tentukan bentuk jamak dalam pesan locale menggunakan pemisah tanda pipa: 'no items | one item | {count} items'.

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>
Sintaks bentuk jamak yang dipisahkan tanda pipa hanya mendukung bentuk jamak kardinal hingga tiga bentuk (zero | one | other). Untuk bahasa dengan aturan bentuk jamak CLDR kompleks (Arab, Rusia, Polandia), gunakan sintaks ICU MessageFormat atau modifier @.plural dengan pemetaan kategori CLDR eksplisit.
5

Tambahkan Rantai Fallback Locale

fallbackLocale bawaan vue-i18n hanya mendukung daftar datar locale fallback, bukan rantai per locale. Pengguna pt-BR dengan kunci yang tidak tersedia melakukan fallback ke bahasa Inggris alih-alih pt-PT. vue-i18n-locale-chain menambahkan rantai penggabungan mendalam yang dapat dikonfigurasi agar pengguna regional selalu melihat terjemahan tersedia yang paling dekat.

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 menggabungkan pesan secara mendalam saat pemuatan. Kumpulan pesan gabungan di-cache oleh sistem reaktivitas vue-i18n sehingga tidak ada penalti performa runtime untuk pencarian fallback.
6

Otomatiskan Penerjemahan

Setelah vue-i18n dikonfigurasi, terjemahkan file JSON locale Anda menggunakan AI. Dari IDE, minta asisten AI menerjemahkan file sumber, atau integrasikan terjemahan ke pipeline CI/CD untuk lokalisasi yang sepenuhnya otomatis.

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

Konfigurasi Rantai Fallback Locale

Konfigurasikan rantai fallback per locale agar pengguna regional melihat terjemahan tersedia yang paling dekat alih-alih langsung beralih ke bahasa Inggris. vue-i18n mendukung fallbackLocale bergaya objek untuk mendefinisikan rantai per locale.

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': { /* ... */ },
  },
})
Objek fallbackLocale memungkinkan Anda mendefinisikan rantai berbeda untuk locale berbeda. Pengguna pt-BR melakukan fallback ke pt lalu en, sedangkan pengguna zh-Hant-TW melakukan fallback ke zh-Hant, zh, lalu en.

Kesalahan Umum

Mencampurkan Mode Legacy dan Composition API

Menggunakan useI18n() dengan legacy: true (default) menyebabkan kesalahan. Atur legacy: false dalam createI18n() jika Anda menggunakan Composition API, atau tetap gunakan $t() dalam template dengan Options API. Jangan mencampurkan kedua mode dalam aplikasi yang sama.

Menggunakan v-html untuk String Terjemahan

Menggunakan v-html untuk merender terjemahan yang mengandung HTML menimbulkan risiko XSS jika nilai interpolasi berasal dari input pengguna. Gunakan komponen &lt;i18n-t&gt; untuk terjemahan dengan HTML atau komponen Vue tersemat — komponen ini aman secara default dan mendukung penyematan komponen reaktif.

Pengguna Regional Melihat Bahasa Inggris, Bukan Bahasa Induk

fallbackLocale milik vue-i18n adalah daftar datar, bukan rantai per locale. pt-BR melakukan fallback ke apa pun dalam daftar (biasanya 'en') dan sepenuhnya melewati pt-PT. Gunakan vue-i18n-locale-chain untuk menambahkan fallback regional yang tepat dengan penggabungan mendalam.

Coba i18n Agent Sekarang

Lepaskan file terjemahan Anda di sini

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

atau klik untuk menjelajahi

Bahasa target

Tidak perlu mendaftarEstimasi instan

Tanya Jawab i18n Vue