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

Índice

O que é Intlayer?

Intlayer é uma biblioteca inovadora e open-source de 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 dinâmica de locale e troca de idioma.

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

Veja o Template da Aplicação no GitHub.

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 locale, 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 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.

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 os arquivos no modo de desenvolvimento, fornece middleware para detecção de locale 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 { type Dictionary, t } from "intlayer";const content = {  key: "home-page",  content: {    title: t({      en: "Hello world",      fr: "Bonjour le monde",      es: "Hola mundo",    }),    metaTitle: t({      en: "Welcome | My Application",      fr: "Bienvenue | Mon Application",      es: "Bienvenido | Mi Aplicación",    }),    metaDescription: t({      en: "Discover your multilingual Nuxt app homepage powered by Intlayer.",      fr: "Découvrez la page d'accueil multilingue de votre application Nuxt propulsée par Intlayer.",      es: "Descubre la página de inicio multilingüe de tu aplicación Nuxt impulsada por Intlayer.",    }),  },} satisfies Dictionary;export default content;

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ó 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.

(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 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:

<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:

<template>  <NuxtLayout>    <NuxtPage />  </NuxtLayout></template>

(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:

<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.

(Opcional) Passo 7: Adicionar Roteamento Localizado à sua aplicação

O Nuxt gerencia automaticamente 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 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):

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

Página Sobre (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

(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 Links. Este componente adiciona automaticamente o prefixo do idioma atual às URLs internas, o que é essencial para SEO e descoberta das páginas.

<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:

<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

(Opcional) Passo 9: Gerenciar Metadados e SEO

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:

<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:

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;

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:

# 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.