Começando a Internacionalizar (i18n) com Intlayer e Nuxt

Veja o Modelo de Aplicação no GitHub.

O que é Intlayer?

Intlayer é uma biblioteca inovadora e de código aberto para internacionalização (i18n) projetada para simplificar o suporte multilíngue em aplicações web modernas.

Com o Intlayer, você pode:

• Gerenciar traduções facilmente usando dicionários declarativos no nível do componente.
• Localizar dinamicamente metadados, rotas e conteúdo.
• Garantir suporte ao TypeScript com tipos gerados automaticamente, melhorando o autocompletar e a detecção de erros.
• Aproveitar recursos avançados, como detecção e troca dinâmica de idioma.

Guia Passo a Passo para Configurar o Intlayer em uma Aplicação Nuxt

Passo 1: Instalar Dependências

Instale os pacotes necessários usando npm:

npm install intlayer vue-intlayernpm install --save-dev nuxt-intlayer

• intlayer

  O pacote principal que fornece ferramentas de internacionalização para gerenciamento de configuração, tradução, declaração de conteúdo, transpiração e comandos CLI.

• vue-intlayer O pacote que integra o Intlayer com a aplicação Vue. Ele fornece os composables para os componentes Vue.

• nuxt-intlayer O módulo Nuxt que integra o Intlayer com aplicações Nuxt. Ele fornece configuração automática, middleware para detecção de localidade, gerenciamento de cookies e redirecionamento de URL.

Passo 2: Configuração do seu projeto

Crie um arquivo de configuração para configurar os idiomas da sua aplicação:

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [      Locales.ENGLISH,      Locales.FRENCH,      Locales.SPANISH,      // Seus outros locais    ],    defaultLocale: Locales.ENGLISH,  },  content: {    contentDir: ["."], // Porque por padrão o Intlayer irá monitorar arquivos de declaração de conteúdo do diretório `./src`  },};export default config;

Através deste arquivo de configuração, você pode configurar URLs localizadas, redirecionamento via middleware, nomes de cookies, a localização e extensão das suas declarações de conteúdo, desabilitar logs do Intlayer no console, e muito mais. Para uma lista completa dos parâmetros disponíveis, consulte a documentação de configuração.

Passo 3: Integre o Intlayer na sua Configuração Nuxt

Adicione o módulo intlayer à sua configuração Nuxt:

import { defineNuxtConfig } from "nuxt/config";export default defineNuxtConfig({  // ... Sua configuração Nuxt existente  modules: ["nuxt-intlayer"],});

O módulo nuxt-intlayer gerencia automaticamente a integração do Intlayer com o Nuxt. Ele configura a construção da declaração de conteúdo, monitora arquivos no modo de desenvolvimento, fornece middleware para detecção de localidade e gerencia o roteamento localizado.

Passo 4: Declare Seu Conteúdo

Crie e gerencie suas declarações de conteúdo para armazenar traduções:

import { t, type Dictionary } from "intlayer";const helloWorldContent = {  key: "helloworld",  content: {    count: t({ en: "count is ", fr: "le compte est ", es: "el recuento es " }),    edit: t({      en: "Edit <code>components/HelloWorld.vue</code> and save to test HMR",      fr: "Éditez <code>components/HelloWorld.vue</code> et enregistrez pour tester HMR",      es: "Edita <code>components/HelloWorld.vue</code> y guarda para probar HMR",    }),    checkOut: t({      pt: "Confira ",      en: "Check out ",      fr: "Vérifiez ",      es: "Compruebe ",    }),    nuxtIntlayer: t({      pt: "Documentação do Nuxt Intlayer",      en: "Nuxt Intlayer documentation",      fr: "Documentation de Nuxt Intlayer",      es: "Documentación de Nuxt Intlayer",    }),    learnMore: t({      pt: "Saiba mais sobre Nuxt em ",      en: "Learn more about Nuxt in the ",      fr: "En savoir plus sur Nuxt dans la ",      es: "Aprenda más sobre Nuxt en la ",    }),    nuxtDocs: t({      pt: "Documentação do Nuxt",      en: "Nuxt Documentation",      fr: "Documentation Nuxt",      es: "Documentación de Nuxt",    }),    readTheDocs: t({      pt: "Clique no logo do Nuxt para saber mais",      en: "Click on the Nuxt logo to learn more",      pt: "Clique no logotipo do Nuxt para saber mais",      fr: "Cliquez sur le logo Nuxt pour en savoir plus",      es: "Haga clic en el logotipo de Nuxt para obtener más información",    }),  },} satisfies Dictionary;export default helloWorldContent;

Suas declarações de conteúdo podem ser definidas em qualquer lugar da sua aplicação, desde que estejam incluídas no diretório contentDir (por padrão, ./src). E correspondam à extensão do arquivo de declaração de conteúdo (por padrão, .content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx}).

Para mais detalhes, consulte a documentação de declaração de conteúdo.

Passo 5: Utilize o Intlayer no Seu Código

Acesse seus dicionários de conteúdo em toda a sua aplicação Nuxt usando o composable useIntlayer:

<script setup lang="ts">import { ref } from "vue";import { useIntlayer } from "vue-intlayer";defineProps({  msg: String,});const {  count,  edit,  checkOut,  nuxtIntlayer,  learnMore,  nuxtDocs,  readTheDocs,} = useIntlayer("helloworld");const countRef = ref(0);</script><template>  <h1>{{ msg }}</h1>  <div class="card">    <button type="button" @click="countRef++">      <count />      {{ countRef }}    </button>    <p v-html="edit"></p>  </div>  <p>    <checkOut />    <a href="https://nuxt.com/docs/getting-started/introduction" target="_blank"      >Nuxt</a    >, <nuxtIntlayer />  </p>  <p>    <learnMore />    <a href="https://nuxt.com" target="_blank"><nuxtDocs /></a>.  </p>  <p class="read-the-docs"><readTheDocs /></p>  <p class="read-the-docs">{{ readTheDocs }}</p></template>

Acessando Conteúdo no Intlayer

O Intlayer oferece diferentes APIs para acessar seu conteúdo:

• Sintaxe baseada em componentes (recomendada): Use a sintaxe <myContent /> ou <Component :is="myContent" /> para renderizar o conteúdo como um Nó do Intlayer. Isso integra-se perfeitamente com o Editor Visual e o CMS.

• Sintaxe baseada em string: Use {{ myContent }} para renderizar o conteúdo como texto simples, sem suporte ao Editor Visual.

• Sintaxe HTML bruta: Use <div v-html="myContent" /> para renderizar o conteúdo como HTML bruto, sem suporte ao Editor Visual.

• Sintaxe de desestruturação: O composable useIntlayer retorna um Proxy com o conteúdo. Esse proxy pode ser desestruturado para acessar o conteúdo mantendo a reatividade.
• Use const content = useIntlayer("myContent"); e {{ content.myContent }} / <content.myContent />.
• Ou use const { myContent } = useIntlayer("myContent"); e {{ myContent }} / <myContent/> para desestruturar o conteúdo.

(Opcional) Passo 6: Alterar o idioma do seu conteúdo

Para alterar o idioma do seu conteúdo, você pode usar a função setLocale fornecida pelo composable useLocale. Essa função permite definir o locale da aplicação e atualizar o conteúdo de acordo.

Crie um componente para alternar entre idiomas:

<template>  <div class="locale-switcher">    <select v-model="selectedLocale" @change="changeLocale">      <option v-for="loc in availableLocales" :key="loc" :value="loc">        {{ getLocaleName(loc) }}      </option>    </select>  </div></template><script setup lang="ts">import { ref, watch } from "vue";import { getLocaleName } from "intlayer";import { useLocale } from "vue-intlayer";// Obter informações de localidade e função setLocaleconst { locale, availableLocales, setLocale } = useLocale();// Rastrear a localidade selecionada com um refconst selectedLocale = ref(locale.value);// Atualizar a localidade quando a seleção mudarconst changeLocale = () => setLocale(selectedLocale.value);// Manter selectedLocale sincronizado com a localidade globalwatch(  () => locale.value,  (newLocale) => {    selectedLocale.value = newLocale;  });</script></template><style scoped>.locale-switcher {  margin: 1rem 0;}select {  padding: 0.5rem;  border-radius: 0.25rem;  border: 1px solid #ccc;}</style>

Então, use este componente nas suas páginas ou layout:

<script setup lang="ts">import { useIntlayer } from "vue-intlayer";import LocaleSwitcher from "~/components/LocaleSwitcher.vue";const content = useIntlayer("app"); // Crie o arquivo de declaração intlayer relacionado</script><template>  <div>    <header>      <LocaleSwitcher />    </header>    <main>      <NuxtPage />    </main>  </div></template>

(Opcional) Passo 7: Adicione Roteamento localizado à sua aplicação

O Nuxt lida automaticamente com o roteamento localizado ao usar o módulo nuxt-intlayer. Isso cria rotas para cada idioma automaticamente com base na estrutura do diretório das suas páginas.

Exemplo:

pages/├── index.vue          → /, /fr, /es├── about.vue          → /about, /fr/about, /es/about└── contact/    └── index.vue      → /contact, /fr/contact, /es/contact

Para criar uma página localizada, basta criar seus arquivos Vue no diretório pages/:

<script setup lang="ts">import { useIntlayer } from "vue-intlayer";const content = useIntlayer("about");</script><template>  <div>    <h1>{{ content.title }}</h1>    <p>{{ content.description }}</p>  </div></template>

O módulo nuxt-intlayer irá automaticamente:

• Detectar o idioma preferido do usuário
• Gerenciar a troca de idioma via URL
• Definir o atributo <html lang=""> apropriado
• Gerenciar cookies de idioma
• Redirecionar os usuários para a URL localizada apropriada

(Opcional) Passo 8: Criando um Componente de Link Localizado

Para garantir que a navegação da sua aplicação respeite o idioma atual, você pode criar um componente personalizado LocalizedLink. Este componente automaticamente adiciona o prefixo do idioma atual às URLs internas.

<template>  <NuxtLink :to="localizedHref" v-bind="$attrs">    <slot />  </NuxtLink></template><script setup lang="ts">import { computed } from "vue";import { getLocalizedUrl } from "intlayer";import { useLocale } from "vue-intlayer";const props = defineProps({  to: {    type: String,    required: true,  },});const { locale } = useLocale();// Verifica se o link é externoconst isExternalLink = computed(() => /^https?:\/\//.test(props.to || ""));// Cria um href localizado para links internosconst localizedHref = computed(() =>  isExternalLink.value ? props.to : getLocalizedUrl(props.to, locale.value));</script>

Então use este componente em toda a sua aplicação:

<template>  <div>    <LocalizedLink to="/about">      {{ content.aboutLink }}    </LocalizedLink>    <LocalizedLink to="/contact">      {{ content.contactLink }}    </LocalizedLink>  </div></template><script setup lang="ts">import { useIntlayer } from "vue-intlayer";import LocalizedLink from "~/components/LocalizedLink.vue";const content = useIntlayer("home");</script>

(Opcional) Passo 9: Gerenciar Metadados e SEO

O Nuxt oferece excelentes capacidades de SEO. Você pode usar o Intlayer para gerenciar metadados localizados:

<script setup lang="ts">import { useSeoMeta } from "nuxt/app";import { getIntlayer } from "intlayer";import { useLocale } from "vue-intlayer";const { locale } = useLocale();const content = getIntlayer("about-meta", locale.value);useSeoMeta({  title: content.title,  description: content.description,});</script><template>  <div>    <h1>{{ content.pageTitle }}</h1>    <p>{{ content.pageContent }}</p>  </div></template>

Crie a declaração de conteúdo correspondente:

import { t, type Dictionary } from "intlayer";import type { useSeoMeta } from "nuxt/app";const aboutMetaContent = {  key: "about-meta",  content: {    title: t({      pt: "Sobre Nós - Minha Empresa",      en: "About Us - My Company",      fr: "À Propos - Ma Société",      es: "Acerca de Nosotros - Mi Empresa",    }),    description: t({      pt: "Saiba mais sobre nossa empresa e nossa missão",      en: "Learn more about our company and our mission",      fr: "En savoir plus sur notre société et notre mission",      es: "Conozca más sobre nuestra empresa y nuestra misión",    }),  },} satisfies Dictionary<Parameters<typeof useSeoMeta>[0]>;export default aboutMetaContent;

Configurar TypeScript

O Intlayer usa a ampliação de módulos para aproveitar os benefícios do TypeScript e tornar sua base de código mais robusta.

Certifique-se de que sua configuração do TypeScript inclua os tipos gerados automaticamente.

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

Configuração do Git

É recomendado ignorar os arquivos gerados pelo Intlayer. Isso permite evitar que eles sejam comitados no seu repositório Git.

Para isso, você pode adicionar as seguintes instruções no seu arquivo .gitignore:

# Ignorar os arquivos gerados pelo Intlayer.intlayer

Extensão VS Code

Para melhorar sua experiência de desenvolvimento com o Intlayer, você pode instalar a extensão oficial Intlayer VS Code Extension.

Instalar no VS Code Marketplace

Esta extensão oferece:

• Autocompletar para chaves de tradução.
• Detecção de erros em tempo real para traduções ausentes.
• Visualizações inline do conteúdo traduzido.
• Ações rápidas para criar e atualizar traduções facilmente.

Para mais detalhes sobre como usar a extensão, consulte a documentação da Extensão Intlayer para VS Code.

Ir Além

Para ir além, você pode implementar o editor visual ou externalizar seu conteúdo usando o CMS.

Histórico do Documento

• 5.5.10 - 2025-06-29: Histórico inicial