Skip to main content

i18n em Vue: configuração completa da internacionalização com vue-i18n

Da instalação à produção: configure vue-i18n com Composition API, trate plurais segundo CLDR, utilize interpolação de componentes e acrescente cadeias inteligentes.

1

Instalar vue-i18n

vue-i18n é o plugin oficial de internacionalização de Vue.js. Oferece traduções reativas, pluralização ao estilo ICU, interpolação de componentes, formatação de datas/números e compatibilidade com Options API e Composition API.

Terminal
npm install vue-i18n@9
2

Configurar vue-i18n

Crie uma instância com createI18n() e registe-a como plugin Vue. Defina mensagens, região predefinida e região de recurso. vue-i18n aceita modo antigo —Options API— e composição —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')
Se vir erros «Not available in legacy mode», está a misturar chamadas Composition API —useI18n()— com modo antigo. Defina legacy: false em createI18n() ou utilize sempre a sintaxe $t() de Options API.
3

Utilizar traduções nos modelos

vue-i18n oferece $t() nos modelos —Options API— e t() através de useI18n() —Composition API—. Ambas aceitam a chave e parâmetros opcionais com nome ou lista para interpolação.

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

Tratar a pluralização

vue-i18n aceita pluralização através de formas separadas por barras e $tc() —modo antigo— ou t() com count —Composition API—. Defina as formas nas mensagens: '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>
A sintaxe com barras aceita apenas plurais cardinais até três formas —zero | one | other—. Em regras CLDR complexas —árabe, russo e polaco—, utilize ICU MessageFormat ou o modificador @.plural com mapas explícitos.
5

Adicionar cadeias de recurso regional

fallbackLocale integrado em vue-i18n só aceita uma lista simples, não cadeias por região. Um utilizador pt-BR com uma chave em falta recorre ao inglês em vez de pt-PT. vue-i18n-locale-chain acrescenta cadeias configuráveis com combinação profunda para mostrar a tradução disponível mais próxima.

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 combina profundamente as mensagens durante o carregamento. O conjunto fica em cache no sistema reativo de vue-i18n, sem penalização de desempenho durante as pesquisas.
6

Automatizar as traduções

Com vue-i18n configurado, traduza os seus ficheiros JSON de região com IA. No seu IDE, peça ao assistente de IA para traduzir o ficheiro de origem ou integre a tradução no pipeline de CI/CD para automatizar totalmente a localização.

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

Configuração da cadeia de recurso regional

Configure cadeias de recurso específicas de cada região para que os utilizadores regionais vejam a tradução disponível mais próxima em vez de passarem diretamente para inglês. vue-i18n aceita fallbackLocale em formato de objeto para definir cadeias por região.

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': { /* ... */ },
  },
})
O objeto fallbackLocale permite definir cadeias diferentes para regiões diferentes. Um utilizador pt-BR recorre a pt e depois a en, enquanto um utilizador zh-Hant-TW recorre a zh-Hant, zh e depois en.

Erros frequentes

Misturar os modos Legacy e Composition API

Utilizar useI18n() com legacy: true (a predefinição) causa erros. Defina legacy: false em createI18n() se utilizar a Composition API ou mantenha $t() nos modelos com a Options API. Não misture os dois modos na mesma aplicação.

Utilizar v-html em cadeias traduzidas

Utilizar v-html para apresentar traduções que contêm HTML representa um risco de XSS se algum valor de interpolação vier da introdução de dados pelo utilizador. Utilize o componente &lt;i18n-t&gt; em traduções com HTML ou componentes Vue incorporados: é seguro por predefinição e aceita a incorporação reativa de componentes.

Os utilizadores regionais veem inglês em vez da região principal

fallbackLocale de vue-i18n é uma lista simples, não uma cadeia por região. pt-BR recorre ao que estiver na lista (normalmente 'en') e ignora totalmente pt-PT. Utilize vue-i18n-locale-chain para acrescentar o recurso regional adequado com combinação profunda.

Experimente já o i18n Agent

Largue aqui o seu ficheiro de tradução

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

ou clique para selecionar

Idiomas de destino

Sem registoEstimativa imediata

Perguntas frequentes sobre Vue i18n