Traduza seu Next.js and Page Router com Intlayer | Internacionalização (i18n)

Índice

Por que Intlayer em vez de alternativas?

Comparado com soluções principais como next-intl 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 Next.js Usando Page Router

1. 1

   Instalar Dependências

   Instale os pacotes necessários usando seu gerenciador de pacotes preferido:

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

   • next-intlayer

     O pacote que integra o Intlayer com o Next.js. Ele fornece provedores de contexto e hooks para internacionalização no Next.js. Além disso, inclui o plugin do Next.js para integrar o Intlayer com Webpack ou Turbopack, assim como middleware para detectar o idioma preferido do usuário, gerenciar cookies e lidar com redirecionamento de URL.

2. 2

   Configure Seu Projeto

   Crie um arquivo de configuração para definir os idiomas suportados pela 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,
         // Adicione seus outros idiomas aqui
       ],
       defaultLocale: Locales.ENGLISH,
     },
   };
   
   export default config;
   

   Através deste arquivo de configuração, você pode configurar URLs localizadas, redirecionamento de 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.

3. 3

   Integrar o Intlayer com a Configuração do Next.js

   Modifique sua configuração do Next.js para incorporar o Intlayer:

   next.config.mjs

   Copiar conteúdo

   Copiar código

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

   import { withIntlayer } from "next-intlayer/server";
   
   /** @type {import('next').NextConfig} */
   const nextConfig = {
     // Sua configuração existente do Next.js
   };
   
   export default withIntlayer(nextConfig);
   

   O plugin withIntlayer() do Next.js é usado para integrar o Intlayer com o Next.js. Ele garante a construção dos arquivos de declaração de conteúdo e os monitora no modo de desenvolvimento. Define as variáveis de ambiente do Intlayer dentro dos ambientes Webpack ou Turbopack. Além disso, fornece aliases para otimizar o desempenho e assegura a compatibilidade com componentes do servidor.

   A função withIntlayer() é uma função promise. Se você quiser usá-la com outros plugins, pode usar await. Exemplo:

   tsx

   Copiar conteúdo

   Copiar código

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

   const nextConfig = await withIntlayer(nextConfig);
   const nextConfigWithOtherPlugins = withOtherPlugins(nextConfig);
   
   export default nextConfigWithOtherPlugins;
   

4. 4

   Configurar Middleware para Detecção de Localidade

   Configure o middleware para detectar e tratar automaticamente a localidade preferida do usuário:

   A partir do Intlayer v9, este middleware respeita a opção routing.enableProxy (true por padrão). Defina routing.enableProxy: false na sua configuração para transformá-lo em um pass-through sem remover este arquivo. Veja as notas de lançamento do v9.

   src/middleware.ts

   Copiar conteúdo

   Copiar código

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

   export { intlayerProxy as middleware } from "next-intlayer/middleware";
   
   export const config = {
     matcher:
       "/((?!api|static|assets|robots|sitemap|sw|service-worker|manifest|.*\\..*|_next).*)",
   };
   

   Adapte o parâmetro matcher para corresponder às rotas da sua aplicação. Para mais detalhes, consulte a documentação do Next.js sobre configuração do matcher.

5. 5

   Definir Rotas Dinâmicas por Localidade

   Implemente o roteamento dinâmico para servir conteúdo localizado com base na localidade do usuário.

   1. Crie Páginas Específicas por Localidade:

      Renomeie o arquivo da sua página principal para incluir o segmento dinâmico [locale].

      bash

      Copiar conteúdo

      Copiar código

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

      mv src/pages/index.tsx src/pages/[locale]/index.tsx
      

   2. Atualize o _app.tsx para Gerenciar a Localização:

      Modifique seu _app.tsx para incluir os provedores do Intlayer.

   3. Configurar getStaticPaths e getStaticProps:

      No seu [locale]/index.tsx, defina os caminhos e propriedades para lidar com diferentes locais.

      src/pages/[locale]/index.tsx

      Copiar conteúdo

      Copiar código

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

      import type { FC } from "react";
      import type { GetStaticPaths, GetStaticProps } from "next";
      import { type Locales, getConfiguration } from "intlayer";
      
      const HomePage: FC = () => <div>{/* Seu conteúdo aqui */}</div>;
      
      export const getStaticPaths: GetStaticPaths = () => {
        const { internationalization } = getConfiguration();
        const { locales } = internationalization;
      
        const paths = locales.map((locale) => ({
          params: { locale },
        }));
      
        return { paths, fallback: false };
      };
      
      export const getStaticProps: GetStaticProps = ({ params }) => {
        const locale = params?.locale as string;
      
        return {
          props: {
            locale,
          },
        };
      };
      
      export default HomePage;
      

   getStaticPaths e getStaticProps garantem que sua aplicação pré-construa as páginas necessárias para todos os locais no Next.js Page Router. Essa abordagem reduz o cálculo em tempo de execução e leva a uma experiência de usuário aprimorada. Para mais detalhes, consulte a documentação do Next.js sobre getStaticPaths e getStaticProps.

6. 6

   Declare Seu Conteúdo

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

   src/pages/[locale]/home.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 homeContent = {
     key: "home",
     content: {
       title: t({
         pt: "Bem-vindo ao Meu Site",
         en: "Welcome to My Website",
         fr: "Bienvenue sur mon site Web",
         es: "Bienvenido a mi sitio web",
       }),
       description: t({
         pt: "Comece editando esta página.",
         en: "Get started by editing this page.",
         fr: "Commencez par éditer cette page.",
         es: "Comience por editar esta página.",
       }),
     },
   } satisfies Dictionary;
   
   export default homeContent;
   

   Para mais informações sobre como declarar conteúdo, consulte o guia de declaração de conteúdo.

7. 7

   Utilize o Conteúdo no Seu Código

   Acesse seus dicionários de conteúdo em toda a sua aplicação para exibir conteúdo traduzido.

   src/pages/[locale]/index.tsx

   Copiar conteúdo

   Copiar código

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

   import type { FC } from "react";
   import { useIntlayer } from "next-intlayer";
   import { ComponentExample } from "@components/ComponentExample";
   
   const HomePage: FC = () => {
     const content = useIntlayer("home");
   
     return (
       <div>
         <h1>{content.title}</h1>
         <p>{content.description}</p>
         <ComponentExample />
         {/* Componentes adicionais */}
       </div>
     );
   };
   
   // ... Resto do código, incluindo getStaticPaths e getStaticProps
   
   export default HomePage;
   

   src/components/ComponentExample.tsx

   Copiar conteúdo

   Copiar código

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

   import type { FC } from "react";
   import { useIntlayer } from "next-intlayer";
   
   export const ComponentExample: FC = () => {
     const content = useIntlayer("component-example"); // Certifique-se de que você tem uma declaração de conteúdo correspondente
   
     return (
       <div>
         <h2>{content.title}</h2>
         <p>{content.content}</p>
       </div>
     );
   };
   

   Ao usar traduções em atributos do tipo string (por exemplo, alt, title, href, aria-label), chame o

   valor da função da seguinte forma:

   html

   Copiar conteúdo

   Copiar código

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

   <img src="{content.image.src.value}" alt="{content.image.value}" />
   <img src="{content.image.src.toString()}" alt="{content.image.toString()}" />
   <img src="{String(content.image.src)}" alt="{String(content.image)}" />
   

   Para saber mais sobre o hook useIntlayer, consulte a documentação.

8. 8

   Internacionalização dos seus metadados

   Opcional

   Caso você queira internacionalizar seus metadados, como o título da sua página, você pode usar a função getStaticProps fornecida pelo Next.js Page Router. Dentro dela, você pode recuperar o conteúdo da função getIntlayer para traduzir seus metadados.

   src/pages/[locale]/metadata.content.ts

   Copiar conteúdo

   Copiar código

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

   import { type Dictionary, t } from "intlayer";
   import { type Metadata } from "next";
   
   const metadataContent = {
     key: "page-metadata",
     content: {
       title: t({
         en: "Create Next App",
         fr: "Créer une application Next.js",
         es: "Crear una aplicación Next.js",
       }),
       description: t({
         en: "Generated by create next app",
         fr: "Généré par create next app",
         es: "Generado por create next app",
       }),
     },
   } satisfies Dictionary<Metadata>;
   
   export default metadataContent;
   

   src/pages/[locale]/index.tsx

   Copiar conteúdo

   Copiar código

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

   import { GetStaticPaths, GetStaticProps } from "next";
   import { getIntlayer, getMultilingualUrls } from "intlayer";
   import { useIntlayer } from "next-intlayer";
   import Head from "next/head";
   import type { FC } from "react";
   
   interface HomePageProps {
     locale: string;
     metadata: {
       title: string;
       description: string;
     };
     multilingualUrls: Record<string, string>;
   }
   
   const HomePage: FC<HomePageProps> = ({
     metadata,
     multilingualUrls,
     locale,
   }) => {
     const content = useIntlayer("page");
   
     return (
       <div>
         <Head>
           <title>{metadata.title}</title>
           <meta name="description" content={metadata.description} />
           {/* Gerar tags hreflang para SEO */}
           {Object.entries(multilingualUrls).map(([lang, url]) => (
             <link key={lang} rel="alternate" hrefLang={lang} href={url} />
           ))}
           <link rel="canonical" href={multilingualUrls[locale]} />
         </Head>
   
         {/* Conteúdo da página */}
         <main>{/* Seu conteúdo da página aqui */}</main>
       </div>
     );
   };
   
   export const getStaticProps: GetStaticProps<HomePageProps> = async ({
     params,
   }) => {
     const locale = params?.locale as string;
   
     const metadata = getIntlayer("page-metadata", locale);
   
     /**
      * Gera um objeto contendo todas as URLs para cada localidade.
      *
      * Exemplo:
      * ```ts
      *  getMultilingualUrls('/about');
      *
      *  // Retorna
      *  // {
      *  //   en: '/about',
      *  //   fr: '/fr/about',
      *  //   es: '/es/about',
      *  // }
      * ```
      */
     const multilingualUrls = getMultilingualUrls("/");
   
     return {
       props: {
         locale,
         metadata,
         multilingualUrls,
       },
     };
   };
   
   export default HomePage;
   
   // ... Resto do código incluindo getStaticPaths
   

   Note que a função getIntlayer importada de next-intlayer retorna seu conteúdo encapsulado em um IntlayerNode, permitindo a integração com o editor visual. Em contraste, a função getIntlayer importada de intlayer retorna seu conteúdo diretamente, sem propriedades adicionais.

   Saiba mais sobre a otimização de metadados na documentação oficial do Next.js.

9. 9

   Alterar o idioma do seu conteúdo

   Opcional

   Para alterar o idioma do seu conteúdo no Next.js, a forma recomendada é usar o componente Link para redirecionar os usuários para a página localizada apropriada. O componente Link permite o pré-carregamento da página, o que ajuda a evitar um recarregamento completo da página.

   src/components/LanguageSwitcher.tsx

   Copiar conteúdo

   Copiar código

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

   import {
     Locales,
     getHTMLTextDir,
     getLocaleName,
     getLocalizedUrl,
   } from "intlayer";
   import { useLocalePageRouter } from "next-intlayer";
   import { type FC } from "react";
   import Link from "next/link";
   
   const LocaleSwitcher: FC = () => {
     const { locale, pathWithoutLocale, availableLocales } = useLocalePageRouter();
   
     return (
       <div>
         <button popoverTarget="localePopover">{getLocaleName(locale)}</button>
         <div id="localePopover" popover="auto">
           {availableLocales.map((localeItem) => (
             <Link
               href={getLocalizedUrl(pathWithoutLocale, localeItem)}
               hrefLang={localeItem}
               key={localeItem}
               aria-current={locale === localeItem ? "page" : undefined}
               onClick={() => setLocale(localeItem)}
             >
               <span>
                 {/* Local - ex. FR */}
                 {localeItem}
               </span>
               <span>
                 {/* Idioma em seu próprio local - ex. Français */}
                 {getLocaleName(localeItem, locale)}
               </span>
               <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>
                 {/* Idioma na Localização atual - ex. Francés com a localização atual definida para Locales.SPANISH */}
                 {getLocaleName(localeItem)}
               </span>
               <span dir="ltr" lang={Locales.ENGLISH}>
                 {/* Idioma em Inglês - ex. French */}
                 {getLocaleName(localeItem, Locales.ENGLISH)}
               </span>
             </Link>
           ))}
         </div>
       </div>
     );
   };
   

   Uma forma alternativa é usar a função setLocale fornecida pelo hook useLocale. Esta função não permitirá o pré-carregamento da página e recarregará a página.

   Neste caso, sem redirecionamento usando router.push, apenas o código do lado do servidor mudará o idioma do conteúdo.

   src/components/LocaleSwitcher.tsx

   Copiar conteúdo

   Copiar código

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

   "use client";
   
   import { useLocale } from "next-intlayer";
   import { getLocalizedUrl } from "intlayer";
   
   // ... Resto do código
   
   const { setLocale } = useLocale();
   
   return (
     <button onClick={() => setLocale(Locales.FRENCH)}>Mudar para Francês</button>
   );
   

   A API useLocalePageRouter é a mesma que useLocale. Para saber mais sobre o hook useLocale, consulte a documentação.

   Referências da documentação:

   • hook getLocaleName
   • hook getLocalizedUrl
   • hook getHTMLTextDir
   • atributo hrefLang
   • atributo lang
   • atributo dir
   • atributo aria-current

10. 10

    Criando um Componente de Link Localizado

    Opcional

    Para garantir que a navegação da sua aplicação respeite a localidade atual, você pode criar um componente Link personalizado. Este componente adiciona automaticamente o prefixo do idioma atual às URLs internas. Por exemplo, quando um usuário que fala francês clica em um link para a página "Sobre", ele é redirecionado para /fr/about em vez de /about.

    Esse comportamento é útil por várias razões:

    • SEO e Experiência do Usuário: URLs localizadas ajudam os motores de busca a indexar corretamente páginas específicas por idioma e fornecem aos usuários conteúdo em seu idioma preferido.
    • Consistência: Ao usar um link localizado em toda a sua aplicação, você garante que a navegação permaneça dentro do idioma atual, evitando mudanças inesperadas de idioma.
    • Manutenção: Centralizar a lógica de localização em um único componente simplifica o gerenciamento das URLs, tornando seu código mais fácil de manter e expandir conforme sua aplicação cresce.

    Abaixo está a implementação de um componente Link localizado em TypeScript:

    src/components/Link.tsx

    Copiar conteúdo

    Copiar código

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

    "use client";
    
    import { getLocalizedUrl } from "intlayer";
    import NextLink, { type LinkProps as NextLinkProps } from "next/link";
    import { useLocale } from "next-intlayer";
    import { forwardRef, PropsWithChildren, type ForwardedRef } from "react";
    
    /**
     * Função utilitária para verificar se uma URL fornecida é externa.
     * Se a URL começar com http:// ou https://, é considerada externa.
     */
    export const checkIsExternalLink = (href?: string): boolean =>
      /^https?:\/\//.test(href ?? "");
    
    /**
     * Um componente Link personalizado que adapta o atributo href com base na localidade atual.
     * Para links internos, usa `getLocalizedUrl` para prefixar a URL com a localidade (ex: /fr/about).
     * Isso garante que a navegação permaneça dentro do mesmo contexto de localidade.
     */
    export const Link = forwardRef<
      HTMLAnchorElement,
      PropsWithChildren<NextLinkProps>
    >(({ href, children, ...props }, ref: ForwardedRef<HTMLAnchorElement>) => {
      const { locale } = useLocale();
      const isExternalLink = checkIsExternalLink(href.toString());
    
      // Se o link for interno e um href válido for fornecido, obtenha a URL localizada.
      const hrefI18n: NextLinkProps["href"] =
        href && !isExternalLink ? getLocalizedUrl(href.toString(), locale) : href;
    
      return (
        <NextLink href={hrefI18n} ref={ref} {...props}>
          {children}
        </NextLink>
      );
    });
    
    Link.displayName = "Link";
    

    Como Funciona

    • Detecção de Links Externos:
      A função auxiliar checkIsExternalLink determina se uma URL é externa. Links externos são mantidos inalterados porque não precisam de localização.

    • Recuperando a Localização Atual:
      O hook useLocale fornece a localidade atual (por exemplo, fr para francês).

    • Localizando a URL:
      Para links internos (ou seja, não externos), getLocalizedUrl é usado para prefixar automaticamente a URL com a localidade atual. Isso significa que, se seu usuário estiver em francês, passar /about como href será transformado em /fr/about.

    • Retornando o Link:
      O componente retorna um elemento <a> com a URL localizada, garantindo que a navegação seja consistente com a localidade.

    Ao integrar este componente Link em toda a sua aplicação, você mantém uma experiência de usuário coerente e consciente do idioma, além de beneficiar-se de uma melhor SEO e usabilidade.

11. 11

    Otimize o tamanho do seu bundle

    Opcional

    Ao usar next-intlayer, os dicionários são incluídos no bundle para cada página por padrão. Para otimizar o tamanho do bundle, o Intlayer fornece um plugin SWC opcional que substitui inteligentemente as chamadas useIntlayer usando macros. Isso garante que os dicionários sejam incluídos apenas nos bundles das páginas que realmente os utilizam.

    Para ativar essa otimização, instale o pacote @intlayer/swc. Uma vez instalado, o next-intlayer detectará e usará automaticamente o plugin:

    bash

    Copiar conteúdo

    Copiar código

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

    npm install @intlayer/swc --save-dev
    

    Nota: Esta otimização está disponível apenas para Next.js 13 e versões superiores.

    Nota: Este pacote não é instalado por padrão porque os plugins SWC ainda são experimentais no Next.js. Isso pode mudar no futuro.

Configurar TypeScript

O Intlayer utiliza 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

Para manter seu repositório limpo e evitar o commit de arquivos gerados, é recomendado ignorar os arquivos criados pelo Intlayer.

Adicione as seguintes linhas ao 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.

Recursos Adicionais

• Documentação do Intlayer: Repositório GitHub
• Guia do Dicionário: Dicionário
• Documentação de Configuração: Guia de Configuração

Seguindo este guia, você pode integrar efetivamente o Intlayer em sua aplicação Next.js usando o Page Router, possibilitando um suporte robusto e escalável para internacionalização em seus projetos web.

Ir Além

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

Perguntas Frequentes