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

Veja Application Template no GitHub.

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

1. 1

   Instale as 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

   npm install intlayer next-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, transpilações 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 Next.js para integrar o Intlayer com Webpack ou Turbopack, bem como middleware para detectar a localidade preferida do usuário, gerenciar cookies e lidar com redirecionamento de URLs.

2. 2

   Configure Seu Projeto

   Here is the final structure that we will make:

   bash

   Copiar conteúdo

   Copiar código

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

   .├── src│   ├── app│   │   ├── [locale]│   │   │   ├── layout.tsx            # Locale layout for the Intlayer provider│   │   │   ├── page.content.ts│   │   │   └── page.tsx│   │   └── layout.tsx                # Root layout for style and global providers│   ├── components│   │   ├── client-component-example.content.ts│   │   ├── ClientComponentExample.tsx│   │   ├── LocaleSwitcher│   │   │   ├── localeSwitcher.content.ts│   │   │   └── LocaleSwitcher.tsx│   │   ├── server-component-example.content.ts│   │   └── ServerComponentExample.tsx│   └── middleware.ts├── intlayer.config.ts├── next.config.ts├── package.json└── tsconfig.json

   If you don't want locale routing, intlayer can be used as a simple provider / hook. See this guide for more details.

   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;

   Por meio deste arquivo de configuração, você pode configurar URLs localizados, redirecionamento de middleware, nomes de cookies, a localização e extensão de suas declarações de conteúdo, desativar logs do Intlayer no console e muito mais. Para uma lista completa de parâmetros disponíveis, consulte a documentação de configuração.

3. 3

   Integre o Intlayer na Configuração do Next.js

   Configure seu Next.js para usar 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 = {};export default withIntlayer(nextConfig);

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

4. 4

   Configure o Middleware para Detecção de Localidade

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

   src/middleware.ts

   Copiar conteúdo

   Copiar código

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

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

   O intlayerMiddleware é usado para detectar a localidade preferida do usuário e redirecioná-lo para a URL apropriada, conforme especificado na configuração. Além disso, permite salvar a localidade preferida do usuário em um cookie.

   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

   Defina Rotas Dinâmicas de Localidade

   Remova tudo do RootLayout e substitua pelo seguinte código:

   src/app/layout.tsx

   Copiar conteúdo

   Copiar código

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

   import type { PropsWithChildren, FC } from "react";
   import "./globals.css";
   
   const RootLayout: FC<PropsWithChildren> = ({ children }) => children;
   
   export default RootLayout;

   Manter o componente RootLayout vazio permite definir os atributos lang e dir na tag <html>.

   Para implementar o roteamento dinâmico, forneça o caminho para a localidade adicionando um novo layout no seu diretório [locale]:

   src/app/[locale]/layout.tsx

   Copiar conteúdo

   Copiar código

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

   import {
     type Next14LayoutIntlayer,
     IntlayerClientProvider,
   } from "next-intlayer";
   import { Inter } from "next/font/google";
   import { getHTMLTextDir } from "intlayer";
   
   const inter = Inter({ subsets: ["latin"] });
   
   const LocaleLayout: Next14LayoutIntlayer = ({
     children,
     params: { locale },
   }) => (
     <html lang={locale} dir={getHTMLTextDir(locale)}>
       <body className={inter.className}>
         <IntlayerClientProvider locale={locale}>
           {children}
         </IntlayerClientProvider>
       </body>
     </html>
   );
   
   export default LocaleLayout;

   O segmento de caminho [locale] é usado para definir a localidade. Exemplo: /en-US/about se referirá a en-US e /fr/about a fr.

   Nesta etapa, você encontrará o erro: Erro: Faltam as tags <html> e <body> no layout raiz.. Isso é esperado porque o arquivo /app/page.tsx não está mais em uso e pode ser removido. Em vez disso, o segmento de caminho [locale] ativará a página /app/[locale]/page.tsx. Consequentemente, as páginas estarão acessíveis por meio de caminhos como /en, /fr, /es no seu navegador. Para definir a localidade padrão como a página raiz, consulte a configuração do middleware no passo 4.

   Depois, implemente a função generateStaticParams no Layout da sua aplicação.

   src/app/[locale]/layout.tsx

   Copiar conteúdo

   Copiar código

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

   export { generateStaticParams } from "next-intlayer"; // Linha a ser inserida
   
   const LocaleLayout: Next14LayoutIntlayer = ({
     children,
     params: { locale },
   }) => {
     /*... Resto do código*/
   };
   
   export default LocaleLayout;

   generateStaticParams garante que sua aplicação pré-construa as páginas necessárias para todas as localidades, reduzindo a computação em tempo de execução e melhorando a experiência do usuário. Para mais detalhes, consulte a documentação do Next.js sobre generateStaticParams.

6. 6

   Declare Seu Conteúdo

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

   src/app/[locale]/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 pageContent = {
     key: "page",
     content: {
       getStarted: {
         main: t({
           en: "Get started by editing",
           fr: "Commencez par éditer",
           es: "Comience por editar",
           pt: "Comece editando",
         }),
         pageLink: "src/app/page.tsx",
       },
     },
   } satisfies Dictionary;
   
   export default pageContent;

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

   Para mais detalhes, consulte a documentação 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:

   src/app/[locale]/page.tsx

   Copiar conteúdo

   Copiar código

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

   import { ClientComponentExample } from "@components/ClientComponentExample";
   import { ServerComponentExample } from "@components/ServerComponentExample";
   import { type Next14PageIntlayer } from "next-intlayer";
   import { IntlayerServerProvider, useIntlayer } from "next-intlayer/server";
   
   const Page: Next14PageIntlayer = ({ params: { locale } }) => {
     const content = useIntlayer("page", locale);
   
     return (
       <>
         <p>
           {content.getStarted.main}
           <code>{content.getStarted.pageLink}</code>
         </p>
   
         <IntlayerServerProvider locale={locale}>
           <ServerComponentExample />
           <ClientComponentExample />
         </IntlayerServerProvider>
       </>
     );
   };
   
   export default Page;

   • IntlayerClientProvider é usado para fornecer a localidade para componentes do lado do cliente. Ele pode ser colocado em qualquer componente pai, incluindo o layout. No entanto, colocá-lo em um layout é recomendado porque o Next.js compartilha o código do layout entre as páginas, tornando-o mais eficiente. Usando IntlayerClientProvider no layout, você evita reinicializá-lo para cada página, melhorando o desempenho e mantendo um contexto de localização consistente em toda a sua aplicação.

   • IntlayerServerProvider é usado para fornecer a localidade para os filhos do servidor. Ele não pode ser configurado no layout.

     Layout e página não podem compartilhar um contexto de servidor comum porque o sistema de contexto do servidor é baseado em um armazenamento de dados por solicitação (via mecanismo de cache do React), fazendo com que cada “contexto” seja recriado para diferentes segmentos da aplicação. Colocar o provedor em um layout compartilhado quebraria esse isolamento, impedindo a propagação correta dos valores do contexto do servidor para seus componentes do servidor.

   src/components/ClientComponentExample.tsx

   Copiar conteúdo

   Copiar código

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

   "use client";
   
   import type { FC } from "react";
   import { useIntlayer } from "next-intlayer";
   
   const ClientComponentExample: FC = () => {
     const content = useIntlayer("client-component-example"); // Crie a declaração de conteúdo relacionada
   
     return (
       <div>
         <h2>{content.title}</h2>
         <p>{content.content}</p>
       </div>
     );
   };

   src/components/ServerComponentExample.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/server";
   
   const ServerComponentExample: FC = () => {
     const content = useIntlayer("server-component-example"); // Crie a declaração de conteúdo relacionada
   
     return (
       <div>
         <h2>{content.title}</h2>
         <p>{content.content}</p>
       </div>
     );
   };

   Se você quiser usar seu conteúdo em um atributo string, como alt, title, href, aria-label, etc., você deve chamar o valor da função, como:

   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

   No caso de você querer internacionalizar seus metadados, como o título da sua página, você pode usar a função generateMetadata fornecida pelo Next.js. Dentro da função, use a função getTranslation para traduzir seus metadados.

   src/app/[locale]/layout.tsx or src/app/[locale]/page.tsx

   Copiar conteúdo

   Copiar código

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

   import {  type IConfigLocales,  getTranslation,  getMultilingualUrls,} from "intlayer";import type { Metadata } from "next";import type { LocalParams } from "next-intlayer";export const generateMetadata = ({  params: { locale },}: LocalParams): Metadata => {  const t = <T>(content: IConfigLocales<T>) => getTranslation(content, 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("/");  const localizedUrl =    multilingualUrls[locale as keyof typeof multilingualUrls];  return {    title: t<string>({      en: "My title",      fr: "Mon titre",      es: "Mi título",      pt: "Meu título",    }),    description: t({      en: "My description",      fr: "Ma description",      es: "Mi descripción",      pt: "Minha descrição",    }),    alternates: {      canonical: localizedUrl,      languages: { ...multilingualUrls, "x-default": "/" },    },    openGraph: {      url: localizedUrl,    },  };};// ... Resto do código

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

9. 9

   Internacionalização do seu sitemap.xml e robots.txt

   Opcional

   Para internacionalizar seu sitemap.xml e robots.txt, você pode usar a função getMultilingualUrls fornecida pelo Intlayer. Esta função permite gerar URLs multilíngues para seu sitemap.

   src/app/sitemap.ts

   Copiar conteúdo

   Copiar código

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

   import { getMultilingualUrls } from "intlayer";
   import type { MetadataRoute } from "next";
   
   const sitemap = (): MetadataRoute.Sitemap => [
     {
       url: "https://example.com",
       alternates: {
         languages: getMultilingualUrls("https://example.com"),
       },
     },
     {
       url: "https://example.com/login",
       alternates: {
         languages: getMultilingualUrls("https://example.com/login"),
       },
     },
     {
       url: "https://example.com/register",
       alternates: {
         languages: getMultilingualUrls("https://example.com/register"),
       },
     },
   ];
   
   export default sitemap;

   src/app/robots.ts

   Copiar conteúdo

   Copiar código

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

   import type { MetadataRoute } from "next";
   import { getMultilingualUrls } from "intlayer";
   
   const getAllMultilingualUrls = (urls: string[]) =>
     urls.flatMap((url) => Object.values(getMultilingualUrls(url)) as string[]);
   
   const robots = (): MetadataRoute.Robots => ({
     rules: {
       userAgent: "*",
       allow: ["/"],
       disallow: getAllMultilingualUrls(["/login", "/register"]),
     },
     host: "https://example.com",
     sitemap: `https://example.com/sitemap.xml`,
   });
   
   export default robots;

   Saiba mais sobre a otimização do sitemap na documentação oficial do Next.js. Saiba mais sobre a otimização do robots.txt na documentação oficial do Next.js.

10. 10

    Alterar o idioma do seu conteúdo

    Opcional

    Para alterar o idioma do seu conteúdo no Next.js, a maneira 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/LocaleSwitcher.tsx

    Copiar conteúdo

    Copiar código

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

    "use client";
    
    import {
      Locales,
      getHTMLTextDir,
      getLocaleName,
      getLocalizedUrl,
    } from "intlayer";
    import { useLocale } from "next-intlayer";
    import { type FC } from "react";
    import Link from "next/link";
    
    const LocaleSwitcher: FC = () => {
      const { locale, pathWithoutLocale, availableLocales, setLocale } =
        useLocale();
    
      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>
                  {/* Localidade - ex.: FR */}
                  {localeItem}
                </span>
                <span>
                  {/* Idioma na sua própria Localidade - ex.: Français */}
                  {getLocaleName(localeItem, locale)}
                </span>
                <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>
                  {/* Idioma na Localidade atual - ex.: Francés com localidade atual definida como 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>
      );
    };

    Referências da documentação:

    • Hook useLocale
    • Hook getLocaleName
    • Hook getLocalizedUrl
    • Hook getHTMLTextDir
    • Atributo hrefLang
    • Atributo lang
    • Atributo dir
    • Atributo aria-current

11. 11

    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 automaticamente prefixa URLs internas com o idioma atual, de forma que, 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.

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

    • SEO e Experiência do Usuário: URLs localizadas ajudam os mecanismos de busca a indexar corretamente as páginas específicas de idioma e fornecem aos usuários conteúdo em seu idioma preferido.
    • Consistência: Usando um link localizado em toda a sua aplicação, você garante que a navegação permaneça dentro da localidade atual, evitando mudanças inesperadas de idioma.
    • Manutenibilidade: Centralizar a lógica de localização em um único componente simplifica o gerenciamento de URLs, tornando sua base de código mais fácil de manter e expandir à medida que 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 é externa.
     * Se a URL começar com http:// ou https://, ela é 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, ele 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

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

    • Recuperando a Localidade Atual:
      O hook useLocale fornece a localidade atual (ex.: 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 transformará 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 se beneficiar de SEO e usabilidade aprimorados.

12. 12

    Otimize o tamanho do seu bundle

    Opcional

    Ao usar o next-intlayer, os dicionários são incluídos no bundle de 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 habilitar essa otimização, instale o pacote @intlayer/swc. Uma vez instalado, o next-intlayer detectará automaticamente e usará 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 só está disponível em Next.js 13 e superior.

    Nota: Este pacote não é instalado por padrão porque o plugin SWC ainda está em fase experimental no Next.js. Isso pode mudar no futuro.

Configure o TypeScript

O Intlayer usa a ampliação de módulos para obter 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 autogerados.

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

Configuração do Git

É recomendável ignorar os arquivos gerados pelo Intlayer. Isso permite evitar que eles sejam enviados para seu repositório Git.

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

# Ignore os arquivos gerados pelo Intlayer.intlayer

Vá Além

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