Intlayer

--- createdAt: 2024-08-11 updatedAt: 2025-08-23 title: vue-i18n vs Intlayer description: Comparação entre vue-i18n e Intlayer para internacionalização (i18n) em apps Vue/Nuxt keywords: - vue-i18n - Intlayer - Internacionalização - i18n - Blog - Vue - Nuxt - JavaScript slugs: - blog - vue-i18n-vs-intlayer --- # vue-i18n VS Intlayer | Internacionalização (i18n) em Vue Este guia compara duas opções populares de i18n para **Vue 3** (e **Nuxt**): **vue-i18n** e **Intlayer**. Focamos nas ferramentas modernas do Vue (Vite, Composition API) e avaliamos: 1. **Arquitetura & organização de conteúdo** 2. **TypeScript & segurança** 3. **Tratamento de traduções faltantes** 4. **Roteamento & estratégia de URL** 5. **Performance & comportamento de carregamento** 6. **Experiência do desenvolvedor (DX), ferramentas & manutenção** 7. **SEO & escalabilidade para grandes projetos** > **resumo**: Ambos podem localizar apps Vue. Se você deseja **conteúdo com escopo de componente**, **tipos TypeScript rigorosos**, **verificações de chaves faltantes em tempo de build**, **dicionários otimizados por tree-shaking**, e **helpers integrados para roteamento/SEO** além de **Editor Visual & traduções com IA**, **Intlayer** é a escolha mais completa e moderna. --- ## Posicionamento em alto nível - **vue-i18n** - A biblioteca i18n padrão para Vue. Formatação flexível de mensagens (estilo ICU), blocos SFC `<i18n>` para mensagens locais, e um grande ecossistema. Segurança e manutenção em larga escala ficam principalmente por sua conta. - **Intlayer** - Modelo de conteúdo centrado em componentes para Vue/Vite/Nuxt com **tipagem TS rigorosa**, **verificações em tempo de build**, **tree-shaking**, **helpers para roteador e SEO**, **Editor Visual/CMS** opcional e **traduções assistidas por IA**. --- ## Comparação de Recursos Lado a Lado (focada em Vue) | Recurso | **Intlayer** | **vue-i18n** | | -------------------------------------------------- | ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | **Traduções próximas aos componentes** | ✅ Sim, conteúdo colocalizado por componente (ex.: `MyComp.content.ts`) | ✅ Sim, via blocos SFC `<i18n>` (opcional) | | **Integração com TypeScript** | ✅ Avançada, tipos **estritos** gerados automaticamente e autocompletar de chaves | ✅ Boas tipagens; **segurança estrita de chaves requer configuração/disciplinas adicionais** | | **Detecção de tradução ausente** | ✅ Avisos/erros em **tempo de build** e exposição no TS | ⚠️ Fallbacks/avisos em tempo de execução | | **Conteúdo rico (componentes/Markdown)** | ✅ Suporte direto para nós ricos e arquivos de conteúdo Markdown | ⚠️ Limitado (componentes via `<i18n-t>`, Markdown via plugins externos) | | **Tradução com IA** | ✅ Fluxos de trabalho integrados usando suas próprias chaves de provedores de IA | ❌ Não integrado | | **Editor Visual / CMS** | ✅ Editor Visual gratuito e CMS opcional | ❌ Não integrado (use plataformas externas) | | **Roteamento localizado** | ✅ Auxiliares para Vue Router/Nuxt para gerar caminhos localizados, URLs e `hreflang` | ⚠️ Não é parte do núcleo (use Nuxt i18n ou configuração personalizada do Vue Router) | | **Geração dinâmica de rotas** | ✅ Sim | ❌ Não fornecido (Nuxt i18n fornece) | | **Pluralização e formatação** | ✅ Padrões de enumeração; formatadores baseados em Intl | ✅ Mensagens no estilo ICU; formatadores Intl | | **Formatos de conteúdo** | ✅ `.ts`, `.js`, `.json`, `.md`, `.txt` (YAML em desenvolvimento) | ✅ `.json`, `.js` (além de blocos SFC `<i18n>`) | | **Suporte ICU** | ⚠️ Em desenvolvimento | ✅ Sim | | **Auxiliares de SEO (sitemap, robots, metadados)** | ✅ Auxiliares integrados (independente de framework) | ❌ Não faz parte do núcleo (Nuxt i18n/comunidade) | | **SSR/SSG** | ✅ Funciona com Vue SSR e Nuxt; não bloqueia a renderização estática | ✅ Funciona com Vue SSR/Nuxt | | **Tree-shaking (enviar apenas o conteúdo usado)** | ✅ Por componente em tempo de build | ⚠️ Parcial; requer divisão manual de código/mensagens assíncronas | | **Carregamento preguiçoso (Lazy loading)** | ✅ Por localidade / por dicionário | ✅ Suporte a mensagens de localidade assíncronas | | **Purgar conteúdo não utilizado** | ✅ Sim (em tempo de build) | ❌ Não incorporado | | **Manutenção em projetos grandes** | ✅ Incentiva estrutura modular, amigável a design systems | ✅ Possível, mas requer disciplina rigorosa de arquivos/namespace | | **Ecossistema / comunidade** | ⚠️ Menor, mas crescendo rapidamente | ✅ Grande e madura no ecossistema Vue | --- ## Comparação detalhada ### 1) Arquitetura e escalabilidade - **vue-i18n**: Configurações comuns usam **catálogos centralizados** por localidade (opcionalmente divididos em arquivos/namespace). Blocos SFC `<i18n>` permitem mensagens locais, mas as equipes frequentemente retornam a catálogos compartilhados conforme os projetos crescem. - **Intlayer**: Promove **dicionários por componente** armazenados ao lado do componente que atendem. Isso reduz conflitos entre equipes, mantém o conteúdo descobrível e limita naturalmente a deriva/chaves não utilizadas. **Por que isso importa:** Em grandes aplicativos Vue ou sistemas de design, **conteúdo modular** escala melhor do que catálogos monolíticos. --- ### 2) TypeScript & segurança - **vue-i18n**: Bom suporte a TS; **tipagem estrita de chaves** normalmente requer esquemas/genéricos personalizados e convenções cuidadosas. - **Intlayer**: **Gera tipos estritos** a partir do seu conteúdo, oferecendo **autocompletar no IDE** e **erros em tempo de compilação** para erros de digitação/chaves ausentes. **Por que isso importa:** Tipagem forte detecta problemas **antes** da execução. --- ### 3) Tratamento de traduções ausentes - **vue-i18n**: Avisos/falhas em **tempo de execução** (ex.: fallback para localidade ou chave). - **Intlayer**: Detecção em **tempo de build** com avisos/erros entre localidades e chaves. **Por que isso importa:** Aplicação em tempo de build mantém a interface de produção limpa e consistente. --- ### 4) Estratégia de roteamento e URLs (Vue Router/Nuxt) - **Ambos** podem funcionar com rotas localizadas. - **Intlayer** fornece auxiliares para **gerar caminhos localizados**, **gerenciar prefixos de localidade** e emitir **`<link rel="alternate" hreflang>`** para SEO. Com Nuxt, complementa o roteamento do framework. **Por que isso importa:** Menos camadas personalizadas e **SEO mais limpo** entre localidades. --- ### 5) Desempenho e comportamento de carregamento - **vue-i18n**: Suporta mensagens de localidade assíncronas; evitar sobrecarregamento é sua responsabilidade (divida os catálogos com cuidado). - **Intlayer**: **Elimina código morto** na build e **carrega preguiçosamente por dicionário/localidade**. Conteúdo não utilizado não é enviado. **Por que isso importa:** Pacotes menores e inicialização mais rápida para apps Vue multilíngues. --- ### 6) Experiência do desenvolvedor e ferramentas - **vue-i18n**: Documentação madura e comunidade consolidada; normalmente você dependerá de **plataformas externas de localização** para fluxos editoriais. - **Intlayer**: Oferece um **Editor Visual gratuito**, **CMS** opcional (compatível com Git ou externalizado), uma **extensão para VSCode**, utilitários **CLI/CI** e **traduções assistidas por IA** usando suas próprias chaves de provedor. **Por que isso importa:** Menor custo operacional e um ciclo de desenvolvimento–conteúdo mais curto. --- ### 7) SEO, SSR & SSG - **Ambos** funcionam com Vue SSR e Nuxt. - **Intlayer**: Adiciona **auxiliares de SEO** (sitemaps/metadados/`hreflang`) que são independentes de framework e funcionam bem com builds Vue/Nuxt. **Por que isso importa:** SEO internacional sem configurações personalizadas complexas. --- ## Por que Intlayer? (Problema & abordagem) A maioria das pilhas i18n (incluindo **vue-i18n**) começa a partir de **catálogos centralizados**: ```bash . ├── locales │ ├── en.json │ ├── es.json │ └── fr.json └── src └── components └── MyComponent.vue ``` Ou com pastas por localidade: ```bash . ├── locales │ ├── en │ │ ├── footer.json │ │ └── navbar.json │ ├── fr │ │ ├── footer.json │ │ └── navbar.json │ └── es │ ├── footer.json │ └── navbar.json └── src └── components └── MyComponent.vue ``` Isso frequentemente desacelera o desenvolvimento conforme os apps crescem: 1. **Para um novo componente** você cria/edita catálogos remotos, conecta namespaces e traduz (frequentemente via copiar/colar manual de ferramentas de IA). 2. **Ao modificar componentes** você procura chaves compartilhadas, traduz, mantém as localidades sincronizadas, remove chaves obsoletas e alinha as estruturas JSON. **Intlayer** delimita o conteúdo **por componente** e mantém-no **junto ao código**, como já fazemos com CSS, histórias, testes e documentação: ```bash . └── components └── MyComponent ├── MyComponent.content.ts └── MyComponent.vue ``` **Declaração de conteúdo** (por componente): ```ts fileName="./components/MyComponent/MyComponent.content.ts" import { t, type Dictionary } from "intlayer"; const componentExampleContent = { key: "component-example", content: { greeting: t({ en: "Hello World", es: "Hola Mundo", fr: "Bonjour le monde", }), }, } satisfies Dictionary; export default componentExampleContent; ``` **Uso no Vue** (Composition API): ```vue fileName="./components/MyComponent/MyComponent.vue" <script setup lang="ts"> import { useIntlayer } from "vue-intlayer"; // Integração Vue const { greeting } = useIntlayer("component-example"); </script> <template> <span>{{ greeting }}</span> </template> ``` Esta abordagem: - **Acelera o desenvolvimento** (declare uma vez; IDE/IA completa automaticamente). - **Limpa a base de código** (1 componente = 1 dicionário). - **Facilita duplicação/migração** (copie um componente e seu conteúdo juntos). - **Evita chaves mortas** (componentes não usados não importam conteúdo). - **Otimiza o carregamento** (componentes carregados sob demanda trazem seu conteúdo junto). --- ## Funcionalidades adicionais do Intlayer (relevantes para Vue) - **Suporte multiplataforma**: Funciona com Vue, Nuxt, Vite, React, Express e mais. - **Gerenciamento de conteúdo baseado em JavaScript**: Declare no código com total flexibilidade. - **Arquivo de declaração por localidade**: Defina todas as localidades e deixe as ferramentas gerarem o restante. - **Ambiente com tipagem segura**: Configuração forte de TS com autocompletar. - **Recuperação simplificada de conteúdo**: Um único hook/composable para buscar todo o conteúdo de um dicionário. - **Base de código organizada**: 1 componente = 1 dicionário na mesma pasta. - **Roteamento aprimorado**: Auxiliares para caminhos e metadados localizados do **Vue Router/Nuxt**. - **Suporte a Markdown**: Importe Markdown remoto/local por localidade; exponha frontmatter para o código. - **Editor Visual gratuito e CMS opcional**: Criação de conteúdo sem plataforma de localização paga; sincronização amigável ao Git. - **Conteúdo tree-shakable**: Envia apenas o que é usado; suporta carregamento preguiçoso. - **Compatível com renderização estática**: Não bloqueia SSG. - **Traduções com IA**: Traduza para 231 idiomas usando seu próprio provedor de IA/chave de API. - **Servidor MCP & extensão VSCode**: Automatize fluxos de trabalho i18n e autoria dentro do seu IDE. - **Interoperabilidade**: Integrações com **vue-i18n**, **react-i18next** e **react-intl** quando necessário. --- ## Quando escolher qual? - **Escolha vue-i18n** se você quiser a **abordagem padrão do Vue**, estiver confortável gerenciando catálogos/namespace por conta própria, e seu app for **pequeno a médio porte** (ou já depender do Nuxt i18n). - **Escolha Intlayer** se você valoriza **conteúdo escopado por componente**, **TypeScript rigoroso**, **garantias em tempo de build**, **tree-shaking**, e ferramentas completas para roteamento/SEO/editor - especialmente para **códigos Vue/Nuxt grandes e modulares**. --- ## Notas práticas de migração (vue-i18n → Intlayer) - **Comece por funcionalidade**: Mova uma rota/visualização/componente de cada vez para os dicionários locais do Intlayer. - **Ponte durante a migração**: Mantenha os catálogos vue-i18n em paralelo; substitua as consultas gradualmente. - **Ative verificações rigorosas**: Permita que a detecção em tempo de compilação identifique cedo chaves/locais ausentes. - **Adote auxiliares de roteador/SEO**: Padronize a detecção de localidade e as tags `hreflang`. - **Meça os pacotes**: Espere **reduções no tamanho dos pacotes** à medida que o conteúdo não utilizado é excluído. --- ## Conclusão Tanto o **vue-i18n** quanto o **Intlayer** localizam bem aplicações Vue. A diferença está em **quanto você precisa construir por conta própria** para alcançar uma configuração robusta e escalável: - Com **Intlayer**, **conteúdo modular**, **TS rigoroso**, **segurança em tempo de build**, **bundles otimizados por tree-shaking** e **ferramentas para router/SEO/editor** vêm **prontos para usar**. - Se sua equipe prioriza **manutenibilidade e velocidade** em um app Vue/Nuxt multi-local, orientado a componentes, o Intlayer oferece a experiência **mais completa** atualmente. Consulte o documento ['Por que Intlayer?'](https://intlayer.org/doc/why) para mais detalhes.