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:

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

VídeoCódigoDemo

www.youtube.com

Open embedded page in fullscreen

ide.intlayer.org

Open embedded page in fullscreen

intlayer-nuxt-4-template.vercel.app

Open embedded page in fullscreen

Veja o Template da Aplicação no GitHub.

1. 1

   Instalar Dependências

   Instale os pacotes necessários usando npm:

   bash

   Copiar conteúdo

   Copiar código

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

   npx intlayer init --interactive
   

   a flag --interactive é opcional. Use intlayer-cli init se você for um agente de IA.

   Este comando detectará seu ambiente e instalará os pacotes necessários. Por exemplo:

   bash

   Copiar conteúdo

   Copiar código

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

   npm install intlayer vue-intlayer
   npm 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.

2. 2

   Configuração do seu projeto

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

   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";
   
   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. 3

   Integre o Intlayer na sua Configuração Nuxt

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

   nuxt.config.ts

   Copiar conteúdo

   Copiar código

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

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

   Copiar conteúdo

   Copiar código

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

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

   Copiar conteúdo

   Copiar código

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

   <script setup lang="ts">
   import { getLocaleName, getLocalizedUrl } from "intlayer";
   import { useLocale } from "vue-intlayer";
   
   // Nuxt importa automaticamente useRoute
   const 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

   Copiar conteúdo

   Copiar código

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

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

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

   Copiar conteúdo

   Copiar código

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

   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

   Copiar conteúdo

   Copiar código

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

   <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

   Copiar conteúdo

   Copiar código

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

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

   Copiar conteúdo

   Copiar código

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

   <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 final
   const 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

   Copiar conteúdo

   Copiar código

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

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

   Copiar conteúdo

   Copiar código

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

   <script setup lang="ts">
   import { useIntlayer } from "vue-intlayer";
   
   // useHead é auto-importado no Nuxt
   const 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

   Copiar conteúdo

   Copiar código

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

   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;
   

10. 6b

    Criar um Layout com Navegação

    Opcional

    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

    Copiar conteúdo

    Copiar código

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

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

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

Perguntas Frequentes