Creation:2025-06-18Last update:2026-05-31

    Traduza seu site Nuxt e Vue usando Intlayer | Internacionalização (i18n)

    Índice

    Por que Intlayer em vez de alternativas?

    Comparado com soluções principais como @nuxtjs/i18n ou i18next, Intlayer é uma solução que vem com otimizações integradas como:

    O Intlayer é otimizado para funcionar perfeitamente com Nuxt, oferecendo roteamento multilíngue, middleware para detecção de localidade, sitemap e todos os recursos necessários para dimensionar a internacionalização (i18n).

    Em vez de carregar arquivos JSON enormes em suas páginas, carregue apenas o conteúdo necessário. O Intlayer ajuda a reduzir o tamanho do bundle e das páginas em até 50%.

    Definir o escopo do conteúdo do seu aplicativo facilita a manutenção de aplicativos de grande escala. Você pode duplicar ou excluir uma única pasta de recursos sem o fardo mental de revisar toda a base de código de seu conteúdo. Além disso, o Intlayer é totalmente tipado (fully typed) para garantir a precisão do seu conteúdo.

    A co-localização de conteúdo reduz o contexto necessário pelos Large Language Models (LLMs). O Intlayer também vem com um conjunto de ferramentas, como uma CLI para testar traduções ausentes,LSP, MCP, e habilidades do agente, para tornar a experiência do desenvolvedor (DX) ainda mais tranquila para os agentes de IA.

    Use a automação para traduzir seu pipeline de CI/CD usando o LLM de sua escolha às custas de seu provedor de IA. O Intlayer também oferece um compilador para automatizar a extração de conteúdo, bem como uma plataforma web para ajudar a traduzir em segundo plano.

    Conectar arquivos JSON enormes a componentes pode levar a problemas de desempenho e reatividade. O Intlayer otimiza o carregamento do seu conteúdo no momento da construção.

    Mais do que apenas uma solução i18n, o Intlayer fornece um [editor visual] auto-hospedado(/pt/doc/concept/editor) e um CMS completo para ajudá-lo a gerenciar seu conteúdo multilíngue em tempo real, facilitando a colaboração com tradutores, redatores e outros membros da equipe. O conteúdo pode ser armazenado local e/ou remotamente.

    Guia passo a passo para configurar o Intlayer em uma aplicação Nuxt

    www.youtube.com

    Veja o Template da Aplicação no GitHub.

    1. Instalar Dependências

      Instale os pacotes necessários usando npm:

      bash
      npm install intlayer vue-intlayernpm install --save-dev nuxt-intlayernpx intlayer init

      • 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 locale, gerenciamento de cookies e redirecionamento de URL.

    2. Configuração do seu projeto

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

      intlayer.config.ts
      import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    locales: [
      Locales.ENGLISH,
      Locales.FRENCH,
      Locales.SPANISH,
      // Seus outros idiomas
    ],
    defaultLocale: Locales.ENGLISH,
  },
};

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 mais. Para uma lista completa dos parâmetros disponíveis, consulte a documentação de configuração.

    3. Integre o Intlayer na sua Configuração Nuxt

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

      nuxt.config.ts
      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 os arquivos no modo de desenvolvimento, fornece middleware para detecção de locale e gerencia o roteamento por localeizado.

    4. Declare Seu Conteúdo

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

      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,cjs,md,mdx,yaml,yml}).
      Para mais detalhes, consulte a documentação de declaração de conteúdo.

    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:

      components/HelloWorld.vue
      <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ó 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 bruto: 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.

    6. Alterar o idioma do seu conteúdo

      Opcional

      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 usando NuxtLink. Usar links em vez de botões para a troca de locale é uma boa prática para SEO e descoberta da página, pois permite que os motores de busca rastreiem e indexem todas as versões localizadas das suas páginas:

      components/LocaleSwitcher.vue
      <script setup lang="ts">import { getLocaleName, getLocalizedUrl } from "intlayer";import { useLocale } from "vue-intlayer";// Nuxt importa automaticamente useRouteconst route = useRoute();const { locale, availableLocales, setLocale } = useLocale();</script><template>  <nav class="locale-switcher">    <NuxtLink      v-for="localeEl in availableLocales"      :key="localeEl"      :to="getLocalizedUrl(route.fullPath, localeEl)"      class="locale-link"      :class="{ 'active-locale': localeEl === locale }"      @click="setLocale(localeEl)"    >      {{ getLocaleName(localeEl) }}    </NuxtLink>  </nav></template>
      Usar NuxtLink com atributos href apropriados (via getLocalizedUrl) garante que os motores de busca possam descobrir todas as variantes de idioma das suas páginas. Isso é preferível à troca de idioma apenas via JavaScript, que os rastreadores de motores de busca podem não seguir.

      Em seguida, configure seu app.vue para usar layouts:

      app.vue
      <template>  <NuxtLayout>    <NuxtPage />  </NuxtLayout></template>

    7. Adicionar Roteamento Localizado à sua aplicação

      Opcional

      O Nuxt gerencia automaticamente o roteamento por localeizado 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:

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

      Para criar páginas localizadas, basta criar seus arquivos Vue no diretório pages/. Aqui estão dois exemplos de páginas:

      Página inicial (pages/index.vue):

      pages/index.vue
      <script setup lang="ts">import { useIntlayer } from "vue-intlayer";const content = useIntlayer("home-page");useHead({  title: content.metaTitle.raw,  meta: [    {      name: "description",      content: content.metaDescription.raw,    },  ],});</script><template>  <h1><content.title /></h1></template>

      Página Sobre (pages/about.vue):

      pages/about.vue
      <script setup lang="ts">import { useIntlayer } from "vue-intlayer";const content = useIntlayer("about-page");useHead({  title: content.metaTitle.raw, // Use .raw para acesso a string primitiva  meta: [    {      name: "description",      content: content.metaDescription.raw, // Use .raw para acesso a string primitiva    },  ],});</script><template>  <h1><content.title /></h1></template>
      Nota: useHead é importado automaticamente no Nuxt. Você pode acessar os valores do conteúdo usando .value (reativo) ou .raw (string primitiva), dependendo das suas necessidades.

      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

    8. Criando um Componente de Link Localizado

      Opcional

      Para garantir que a navegação da sua aplicação respeite o idioma atual, você pode criar um componente personalizado Links. Este componente adiciona automaticamente o prefixo do idioma atual às URLs internas, o que é essencial para SEO e descoberta das páginas.

      components/Links.vue
      <script setup lang="ts">import { getLocalizedUrl } from "intlayer";import { useLocale } from "vue-intlayer";interface Props {  href: string;  locale?: string;}const props = defineProps<Props>();const { locale: currentLocale } = useLocale();// Calcula o caminho finalconst finalPath = computed(() => {  // 1. Verifica se o link é externo  const isExternal = /^https?:\/\//.test(props.href || "");  // 2. Se for externo, retorna como está (NuxtLink cuida da geração da tag <a>)  if (isExternal) return props.href;  // 3. Se for interno, localize a URL  const targetLocale = props.locale || currentLocale.value;  return getLocalizedUrl(props.href, targetLocale);});</script><template>  <NuxtLink :to="finalPath" v-bind="$attrs">    <slot />  </NuxtLink></template>

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

      layouts/default.vue
      <script setup lang="ts">import Links from "~/components/Links.vue";import LocaleSwitcher from "~/components/LocaleSwitcher.vue";</script><template>  <div>    <header>      <LocaleSwitcher />    </header>    <main>      <slot />    </main>    <Links href="/">Início</Links>    <Links href="/about">Sobre</Links>  </div></template>

      Ao usar NuxtLink com caminhos localizados, você garante que:

      • Os motores de busca possam rastrear e indexar todas as versões linguísticas das suas páginas
      • Os usuários possam compartilhar URLs localizadas diretamente
      • O histórico do navegador funcione corretamente com URLs prefixadas pelo locale

    9. Gerenciar Metadados e SEO

      Opcional

      O Nuxt oferece excelentes capacidades de SEO através do composable useHead (auto-importado). Você pode usar o Intlayer para gerenciar metadados localizados utilizando o acessador .raw ou .value para obter o valor primitivo da string:

      pages/about.vue
      <script setup lang="ts">import { useIntlayer } from "vue-intlayer";// useHead é auto-importado no Nuxtconst content = useIntlayer("about-page");useHead({  title: content.metaTitle.raw, // Use .raw para acesso ao valor primitivo da string  meta: [    {      name: "description",      content: content.metaDescription.raw, // Use .raw para acessar a string primitiva    },  ],});</script><template>  <h1><content.title /></h1></template>
      Alternativamente, você pode usar a função import { getIntlayer } from "intlayer" para obter o conteúdo sem reatividade do Vue.

      Acessando valores do conteúdo:

      • Use .raw para obter o valor primitivo da string (não reativo)
      • Use .value para obter o valor reativo
      • Use a sintaxe de componente <content.key /> para suporte ao Visual Editor

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

      pages/about-page.content.ts
      import { t, type Dictionary } from "intlayer";

const aboutPageContent = {
  key: "about-page",
  content: {
    metaTitle: t({
      en: "Sobre Nós - Minha Empresa",
      fr: "À Propos - Ma Société",
      es: "Acerca de Nosotros - Mi Empresa",
    }),
    metaDescription: t({
      en: "Saiba mais sobre nossa empresa e nossa missão",
      fr: "En savoir plus sur notre société et notre mission",
      es: "Conozca más sobre nuestra empresa y nuestra misión",
    }),
    title: t({
      en: "Sobre Nós",
      fr: "À Propos",
      es: "Acerca de Nosotros",
    }),
  },
} satisfies Dictionary;

export default aboutPageContent;

    (Opcional) Passo 6b: Criar um Layout com Navegação

    Os layouts do Nuxt permitem definir uma estrutura comum para suas páginas. Crie um layout padrão que inclua o seletor de idioma e a navegação:

    layouts/default.vue
    <script setup lang="ts">import Links from "~/components/Links.vue";import LocaleSwitcher from "~/components/LocaleSwitcher.vue";</script><template>  <div>    <header>      <LocaleSwitcher />    </header>    <main>      <slot />    </main>    <Links href="/">Início</Links>    <Links href="/about">Sobre</Links>  </div></template>

    O componente Links (mostrado abaixo) garante que os links de navegação interna sejam automaticamente localizados.

    Configuração do Git

    É recomendado ignorar os arquivos gerados pelo Intlayer. Isso permite que você evite comitá-los no seu repositório Git.

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

    .gitignore
    # Ignorar os arquivos gerados pelo Intlayer.intlayer

    Extensão do 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 Intlayer VS Code Extension.

    Ir Além

    Para ir mais longe, você pode implementar o editor visual ou externalizar seu conteúdo usando o CMS.

    Vite e Vue
    Vite e Solid