Migrando de @nuxtjs/i18n para Intlayer

Por que migrar de @nuxtjs/i18n para Intlayer?

Estratégias de Migração

Como o @nuxtjs/i18n é executado usando vue-i18n sob o capô, há duas estratégias complementares para migrar para o Intlayer:

1. Adaptador de Compatibilidade (Recomendado para apps existentes) — Instale o @intlayer/vue-i18n e o nuxt-intlayer. Isso expõe exatamente a mesma API que o vue-i18n, delegando todo o trabalho de tradução de bastidores para o Intlayer. Mantenha intactas suas chamadas para $t, useI18n() e do roteador do Nuxt — a única alteração é a inicialização.

2. Migração Completa — Substitua de forma progressiva a API contida no @nuxtjs/i18n voltando-se aos hooks integrados nativos vinculados e oferecidos pelo uso do Intlayer (useIntlayer) assim como, de carona no mesmo conceito de trabalho, vá colocalizando tudo relacionado a conteúdo e variáveis diretamente sob arquivos .content.ts perto a proximidade de seus respectivos componentes.

Este guia foca inicialmente em tratar a fundo a Estratégia 1 (que aborda o uso rápido através do tal adaptador de compatibilidade em substituição direta) antes de mergulhar na completa migração, opcional em questão.

Índice

Migração Rápida

As etapas a seguir são o mínimo necessário para executar seu aplicativo Nuxt existente no Intlayer, sem fazer alterações no código de seus componentes.

1. 1

   Instale as Dependências

   Instale o pacote principal do Intlayer e o adaptador de compatibilidade:

   bash

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   npm install intlayer vue-intlayer nuxt-intlayer @intlayer/vue-i18n @intlayer/sync-json-pluginnpx intlayer init

   Fique a vontade para manter o @nuxtjs/i18n instalado e ativo seguramente ao longo de sua etapa de migração do código (estaremos desabilitando e varrendo o tal serviço brevemente na definição/configuração principal do Nuxt ali no passo adiante).

2. 2

   Configure o Intlayer

   O comando intlayer init cria um arquivo inicial intlayer.config.ts. Atualize-o para corresponder aos seus locales existentes e direcione o plugin syncJSON aos seus arquivos de mensagens:

   intlayer.config.ts

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   import { Locales, type IntlayerConfig } from "intlayer";
   import { syncJSON } from "@intlayer/sync-json-plugin";
   
   const config: IntlayerConfig = {
     internationalization: {
       locales: [
         Locales.ENGLISH,
         Locales.FRENCH,
         Locales.SPANISH,
         // Adicione todos os seus locales existentes aqui
       ],
       defaultLocale: Locales.ENGLISH,
     },
     plugins: [
       syncJSON({
         // Corresponde à sintaxe de espaço reservado do vue-i18n: {name}
         format: "icu",
         source: ({ locale }) => `./locales/${locale}.json`,
         location: "locales",
       }),
     ],
   };
   
   export default config;

   source mapeia um locale para o caminho do arquivo JSON correspondente. location diz ao observador (watcher) do Intlayer qual pasta monitorar para alterações. A opção format: 'icu' garante que espaços reservados do vue-i18n sejam analisados corretamente.

3. 3

   Atualize a Configuração do Nuxt

   Troque a representação em tela que declarava antes como módulo o @nuxtjs/i18n para em seguida adicionar no seu nuxt.config.ts o módulo atual sendo nuxt-intlayer. Este plugin em si que pertence e constrói debaixo da base fornecida pelo sistema do Intlayer adiciona "em seus bastidores" injeções de reencaminhamentos automáticos via criação de aliases nos seus módulos com resultados que garantem e efetuam por onde ocorra declarações chamadas pelo import { useI18n } from 'vue-i18n' passem imperceptíveis e perfeitamente bem ao @intlayer/vue-i18n.

   nuxt.config.ts

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   export default defineNuxtConfig({
     // Desapareça com o respectivo '@nuxtjs/i18n'
     modules: ["nuxt-intlayer"],
   });

   Acabou a necessidade para ter que embutir objetos do tipo i18n contendo formatações para o uso e controle do framework Nuxt Agora, por detrás de tudo e no próprio momento do build (build-time), é a inteligência do sistema principal do Intlayer que orquestra tudo englobando todos recursos relativos às identificações e mapeamentos por país, redirecionamentos a certas rotas bem como o gerenciamento do carregamento prévio que o material atrelado por trás embutirá.

Isso é tudo para a migração rápida. Seu aplicativo Nuxt agora está executando perfeitamente bem ao decorrer das chamadas que antes serviam em formato de $t somados também das chamadas via funcionalidade com nome igual a useI18n() a partir de dentro das suas próprias estruturas atadas no sistema operacional englobado e alimentado internamente a plataforma e ecossistema pelo uso contínuo de suporte atrelados as raízes de base Intlayer.

Migração Completa

As etapas a seguir são opcionais e podem ser feitas gradativamente. Elas desbloqueiam o conjunto completo das funcionalidades do Intlayer: editor visual, CMS, arquivos de conteúdo tipados, automação de tradução por IA e muito mais.

1. 4

   Renomeie Explícitamente as Importações (Opcional)

   Opcional

   O plugin atrelado à ferramenta Intlayer engloba nativamente a estrutura e lida com base no nível central da máquina empacotadora a parte relacionada a aliases no projeto. Ainda assim, caso seu interesse prefira forçar como explícitos os caminhos para uso nas suas fontes internas ou dependências diretas de origem nativa em particular, lhe daremos opções fáceis manuais voltadas para isso:

   Mostrar todo o conteúdo da tabela

   Mostrar todo o conteúdo da tabela

   Abrir a tabela em um modal para ver todo o conteúdo claramente

   Antes	Depois
   import { useI18n } from 'vue-i18n'	import { useI18n } from '@intlayer/vue-i18n'

   Essas são substituições diretas (drop-in) — nenhuma alteração de assinaturas de chamadas, argumentos ou tipos de retorno é necessária.

2. 5

   Habilite a Automação de Tradução por IA

   Opcional

   Com o Intlayer configurado, você pode usar a CLI para preencher traduções ausentes automaticamente:

   bash

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   # Testar traduções ausentes (adicionar ao CI)npx intlayer test# Preencher traduções ausentes usando IAnpx intlayer fill

   Adicione a configuração de IA ao seu intlayer.config.ts:

   intlayer.config.ts

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   import { Locales, type IntlayerConfig } from "intlayer";
   import { syncJSON } from "@intlayer/sync-json-plugin";
   
   const config: IntlayerConfig = {
     internationalization: {
       locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
       defaultLocale: Locales.ENGLISH,
     },
     plugins: [
       syncJSON({
         format: "icu",
         source: ({ locale }) => `./locales/${locale}.json`,
         location: "locales",
       }),
     ],
     ai: {
       apiKey: process.env.OPENAI_API_KEY,
       // provider: "openai",     // padrão
       // model: "gpt-4o-mini",   // padrão
     },
   };
   
   export default config;

   Verifique a Documentação da CLI do Intlayer para explorar todas as opções disponíveis.

O que pode ser excluído pós-migração

Uma vez que o adaptador de compatibilidade esteja implementado, o seguinte boilerplate padrão do @nuxtjs/i18n pode ser excluído:

Quando você estiver pronto para ir mais além, o Intlayer descobre automaticamente todos os arquivos .content.ts e .content.json em qualquer lugar da sua base de código (por padrão, em qualquer lugar sob ./src). Basta colocar um arquivo my-component.content.ts ao lado do seu MyComponent.vue, e o Intlayer o detectará em tempo de build sem necessidade de configuração adicional — não são necessários imports, registros ou um arquivo index central. Isso torna a co-localização das traduções com páginas e componentes totalmente fluida.

Configuração do TypeScript

O Intlayer usa aumento de módulo (module augmentation) para fornecer IntelliSense completo no TypeScript (autocompletar) para as chaves de tradução. Certifique-se de que o seu arquivo tsconfig.json inclua os tipos gerados automaticamente:

{  // ... Suas configurações existentes de TypeScript  "include": [    // ... Suas configurações existentes de TypeScript    ".intlayer/**/*.ts", // Inclui os tipos gerados automaticamente  ],}

Configuração do Git

Adicione o diretório gerado pelo Intlayer ao seu .gitignore:

# Ignora arquivos gerados pelo Intlayer.intlayer

Explore Além

• Editor Visual — Gerencie traduções visualmente no seu navegador: Editor Visual Intlayer
• CMS — Externalize o conteúdo e gerencie remotamente: CMS do Intlayer
• Extensão para VS Code — Obtenha autocompletar de tradução e detecção de erros em tempo real: Extensão do VS Code para o Intlayer
• Referência da CLI — Lista completa de comandos da CLI: CLI do Intlayer
• Intlayer com Nuxt — Guida completa de configuração para Nuxt: intlayerwithnuxt.md
• Intlayer com Vue — Guida completa de configuração para Vue: intlayerwithvite+vue.md