Como escolher a biblioteca de i18n certa para Vue

"Vue i18n" é tanto um termo genérico quanto o nome da biblioteca que quase todo mundo instala. Isso é conveniente e enganoso ao mesmo tempo: vue-i18n é um bom padrão, mas não é a única opção, e as perguntas que deveriam guiar essa escolha (SSR ou não, quantas páginas, quem escreve as traduções) raramente são feitas antes do npm install.

Este guia faz essas perguntas primeiro e, em seguida, mapeia as respostas para as bibliotecas mais adequadas, tanto para Vite + Vue puro quanto para Nuxt.

Índice

Seis perguntas a responder antes de comparar bibliotecas

1. Vite SPA ou Nuxt? Em uma SPA, o custo do catálogo é um problema de bundle JS. No Nuxt, é também um problema de payload HTML, porque as mensagens são serializadas no estado de SSR e hidratadas. A maioria dos relatos de que "vue-i18n é lento" vem de aplicações Nuxt por esse motivo.
2. Quem escreve as traduções? Desenvolvedores, um TMS, uma agência entregando strings ICU ou um pipeline de IA. O vue-i18n usa sua própria sintaxe de plural separada por barras verticais (pipe), não ICU. Isso importa se as strings vêm de fora.
3. Quantos locales e páginas? Dois locales e cinco páginas podem carregar tudo de uma vez. Dez locales e quarenta rotas não podem, e a estratégia de carregamento se torna o custo principal.
4. Você precisa de tipagem nas chaves? t("cart.totl") compila no vue-i18n a menos que você passe um schema genérico de mensagens, e esse schema entra em conflito com catálogos carregados sob demanda (lazy loading).
5. O que o conteúdo contém? Apenas labels de UI, ou markdown, links no meio de frases e blocos específicos por locale. Conteúdo rico é onde o retorno de string simples do t() se torna incômodo.
6. A CSP é uma restrição? A build padrão do vue-i18n compila mensagens no navegador com new Function. Builds runtime-only precisam do @intlify/unplugin-vue-i18n para pré-compilar em tempo de build.

Anote as respostas. Tudo o que se segue faz referência a elas.

O panorama geral

O ecossistema Vue tem menos bibliotecas de i18n do que o React, e elas vêm de diferentes ondas arquiteturais.

A história do i18n em JavaScript aborda cada onda em detalhes.

A decisão que mais importa: onde o conteúdo fica e quando ele carrega

Duas escolhas estruturais explicam a maior parte da diferença de bundle entre as abordagens:

• Conteúdo centralizado ou delimitado por escopo (scoped). Um único locales/en.json para o app inteiro, ou uma declaração por componente.
• Import estático ou dinâmico. Tudo na inicialização, ou o locale ativo (e idealmente a rota ativa) carregado sob demanda.

O gráfico estima o payload para uma aplicação teórica de 1 a 10 páginas, traduzida em 1 a 10 locales, com cerca de 30 KB de texto por página.

O vue-i18n suporta o eixo dinâmico: usar setLocaleMessage após um import() significa que você deixa de enviar nove locales que ninguém lê. O que ele não oferece é o eixo por página. Um catálogo de locale é um objeto único, e carregá-lo carrega os textos de todas as páginas. Em uma SPA, ninguém percebe. No Nuxt, com o @nuxtjs/i18n e mais de dez páginas, cada rota carrega as strings de todas as outras rotas duas vezes: no chunk JS e no SSR payload.

O benchmark Vue mede isso como "vazamento de outras rotas" e "vazamento de outros locales". Se sua resposta para a pergunta 3 foi "muitas páginas", esta seção tem mais peso do que qualquer preferência de API. O artigo sobre i18n por componente vs centralizado aborda o lado de manutenção desse mesmo trade-off.

Os candidatos

Os tamanhos das bibliotecas são do benchmark Vue: plugin mais composable em um componente vazio, após bundling, tree-shaking e minificação, em um app de 10 páginas e 10 locales. O conteúdo é medido separadamente.

Os números são um retrato nas versões do benchmark. Execute-o em sua própria aplicação antes de decidir apenas pelo tamanho.

O tamanho quase zero da biblioteca do Paraglide é por construção: o runtime é gerado dentro do seu repositório, o que significa uma etapa de regeneração antes de cada push e conflitos de merge em arquivos gerados. O Intlayer precisa do vite-intlayer (ou do módulo Nuxt), portanto não pode rodar sem uma etapa de build.

Combine suas respostas com uma biblioteca

Onde cada biblioteca deixa a desejar

• vue-i18n: a mais pesada do conjunto, formato de plural próprio, tipos são opcionais e frágeis com lazy loading, sem divisão automática por rota, chaves não utilizadas acumulam silenciosamente. Deixar legacy: true em um app Vue 3 mantém a camada de compatibilidade do Vue 2 e perde a tipagem de useI18n().
• @nuxtjs/i18n: herda todos os pontos acima, e o SSR payload carrega as strings de todas as páginas assim que o projeto passa de uma dúzia de rotas.
• fluent-vue: excelente sintaxe de mensagem, sem tipagem de chaves, e o plugin do Vite carrega todo o conteúdo em todos os idiomas em todas as páginas. A mais pesada no benchmark.
• Paraglide: arquivos gerados commitados no repositório, regeneração antes de cada push, e o locale é lido de cookie ou storage a cada chamada de mensagem em vez de uma store reativa, o que gera processamento extra na troca de locale.
• Intlayer: plugin de build obrigatório, ecossistema menor, suporte parcial a ICU, e conteúdo distribuído pela codebase por design, exigindo ferramentas para exportar um JSON único para um tradutor.

Como cada opção se parece no código

O mesmo componente, um resumo de carrinho com um título e um plural, escrito com cada candidata. A parte interessante não é o template, mas onde o conteúdo fica e o que o vue-tsc sabe sobre ele.

{
  "cart": {
    "title": "Your cart",
    "items": "no item | one item | {count} items"
  }
}

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

const props = defineProps<{ count: number }>();
const { t } = useI18n();
</script>

<template>
  <section>
    <h2>{{ t("cart.title") }}</h2>
    <p>{{ t("cart.items", { count: props.count }, props.count) }}</p>
  </section>
</template>

cart-title = Your cart
cart-items = { $count ->
    [one] { $count } item
   *[other] { $count } items
}

<script setup lang="ts">
import { useFluent } from "fluent-vue";

const props = defineProps<{ count: number }>();
const { $t } = useFluent();
</script>

<template>
  <section>
    <h2>{{ $t("cart-title") }}</h2>
    <p>{{ $t("cart-items", { count: props.count }) }}</p>
  </section>
</template>

{
  "cart_title": "Your cart",
  "cart_items": "{count} items"
}

<script setup lang="ts">
import { m } from "../paraglide/messages.js";

const props = defineProps<{ count: number }>();
</script>

<template>
  <section>
    <h2>{{ m.cart_title() }}</h2>
    <p>{{ m.cart_items({ count: props.count }) }}</p>
  </section>
</template>

import { plural, t, type Dictionary } from "intlayer";

const cartSummaryContent = {
  key: "cart-summary",
  content: {
    title: t({
      pt: "Seu carrinho",
      en: "Your cart",
      fr: "Votre panier",
      es: "Tu carrito",
    }),
    items: t({
      pt: plural({ one: "{{count}} item", other: "{{count}} itens" }),
      en: plural({ one: "{{count}} item", other: "{{count}} items" }),
      fr: plural({ one: "{{count}} article", other: "{{count}} articles" }),
      es: plural({ one: "{{count}} artículo", other: "{{count}} artículos" }),
    }),
  },
} satisfies Dictionary;

export default cartSummaryContent;

<script setup lang="ts">
import { useIntlayer } from "vue-intlayer";

const props = defineProps<{ count: number }>();
const { title, items } = useIntlayer("cart-summary");
</script>

<template>
  <section>
    <h2><title /></h2>
    <p>{{ items(props.count) }}</p>
  </section>
</template>

Já está usando vue-i18n? O adaptador de compatibilidade @intlayer/vue-i18n cria um alias do pacote no nível do bundler, permitindo que useI18n(), $t, plurais pipe e v-t continuem funcionando enquanto o Intlayer fornece o conteúdo. O guia de migração explica como remover o adaptador posteriormente, e há também um guia específico para Nuxt.

Antes de tomar sua decisão

Uma tabela de funcionalidades mostra o que uma biblioteca faz hoje. Estes pontos mostram como será o dia a dia trabalhando com ela.

Verifique a atividade do repositório.

Commits, tempo de resposta em issues e se a última release minor foi lançada este ano. Um design sólido sem mantenedor ativo é uma migração futura garantida.

Não escolha apenas pelo número de downloads no npm.

A biblioteca mais instalada é aquela lançada primeiro, não necessariamente a que melhor atende a uma codebase Vue em 2026. Downloads medem histórico, não adequação.

Pergunte quem financia o mantenedor e o que eles vendem.

O vue-i18n é apoiado pelo Crowdin, assim como o next-intl e o svelte-i18n. O i18next é apoiado pelo Locize. Tolgee, Paraglide (inlang) e Intlayer operam suas próprias plataformas. Um fornecedor cuja receita vem da hospedagem de traduções tem pouco interesse em tornar a tradução gratuita dentro do seu toolchain. O Intlayer é o único do grupo que oferece tradução por IA via CLI com sua própria chave de API e um CMS que você pode auto-hospedar.

Está pronta para agentes de IA?

Agentes ainda enfrentam desafios com i18n: esquecem locales, inventam chaves e misturam sintaxes de mensagens. A biblioteca oferece Agent Skills ou um servidor MCP para que o agente possa listar, preencher e testar o conteúdo? E o carregamento de conteúdo é otimizado por padrão, ou alguém precisa revisar namespaces e imports dinâmicos a cada trimestre?

Segurança de tipos pronta para uso (out of the box).

Não "pode ser tipado com configurações adicionais", mas "uma chave incorreta falha o tsc em uma instalação limpa". Verifique o que acontece com uma chave inexistente e com um locale que esteja sem uma tradução.

Detecção de conteúdo não utilizado.

Catálogos só crescem. O build do Intlayer remove campos não utilizados e registra essas ocorrências (build.purge). O Paraglide atinge isso por arquitetura, já que uma função de mensagem não chamada é eliminada via tree-shaking. As demais bibliotecas deixam essa limpeza por sua conta.

Experiência de desenvolvimento (Developer Experience).

Tempo de configuração até a primeira string traduzida, um LSP ou extensão do VS Code que mostra a tradução ao passar o mouse e navega até a declaração, uma CLI para preencher, testar e enviar (push), além de uma forma para não desenvolvedores editarem conteúdo (editor visual ou CMS) sem a necessidade de um pull request.

Perguntas Frequentes

Indo além

• Benchmark Vue i18n: tamanho de bundle, vazamento de conteúdo e tempos de troca de locale
• Vue i18n: como o vue-i18n funciona e seus pontos fracos e o artigo sobre Nuxt i18n
• vue-i18n vs Intlayer, funcionalidade por funcionalidade e o benchmark vue-i18n vs Intlayer
• O vue-i18n está desatualizado?
• A história do i18n em JavaScript
• i18n baseado em compilador vs declarativo
• i18n por componente vs centralizado
• Configurar i18n em uma aplicação Vite + Vue e em uma aplicação Nuxt
• O mesmo guia para React, Svelte e Solid