Começando com a internacionalização (i18n) com Intlayer e Next.js 14 com App Router

O que é Intlayer?

Intlayer é uma biblioteca inovadora, de código aberto, de internacionalização (i18n) projetada para simplificar o suporte multilíngue em aplicações web modernas. O Intlayer se integra perfeitamente ao mais recente framework Next.js 14, incluindo seu poderoso App Router. Ele é otimizado para funcionar com Server Components para renderização eficiente e é totalmente compatível com Turbopack (a partir do Next.js >= 15).

Com o Intlayer, você pode:

• Gerenciar facilmente traduções usando dicionários declarativos no nível do componente.
• Localizar dinamicamente metadados, rotas e conteúdo.
• Acessar traduções em componentes de cliente e servidor.
• Garantir suporte a TypeScript com tipos autogerados, melhorando a autocompletação e detecção de erros.
• Beneficiar-se de recursos avançados, como detecção e troca dinâmica de idiomas.

O Intlayer é compatível com Next.js 12, 13, 14 e 15. Se você está usando o Next.js Page Router, pode consultar este guia. Para Next.js 15 com ou sem turbopack, consulte este guia.

Guia Passo a Passo para Configurar o Intlayer em uma Aplicação Next.js

Passo 1: Instalar Dependências

Instale os pacotes necessários usando npm:

npm install intlayer next-intlayer

• intlayer

  O pacote principal que fornece ferramentas de internacionalização para gerenciamento de configurações, tradução, declaração de conteúdo, transpilaçã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 com Next.js. Além disso, inclui o plugin do Next.js para integrar o Intlayer com Webpack ou Turbopack, bem como middleware para detectar o idioma preferido do usuário, gerenciar cookies e lidar com redirecionamento de URL.

Passo 2: Configurar 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 de middleware, nomes de cookies, a localização e extensão de suas declarações de conteúdo, desabilitar logs do Intlayer no console e mais. Para uma lista completa de parâmetros disponíveis, consulte a documentação de configuração.

Passo 3: Integrar o Intlayer na Sua Configuração Next.js

Configure sua configuração do Next.js para usar o Intlayer:

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 dos arquivos de declaração de conteúdo e os monitora no modo de desenvolvimento. Define variáveis de ambiente do Intlayer dentro dos ambientes Webpack ou Turbopack. Além disso, fornece aliases para otimizar o desempenho e garantir compatibilidade com componentes do servidor.

Passo 4: Configurar Middleware para Detecção de Idioma

Configure o middleware para detectar o idioma preferido do usuário:

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 o idioma preferido do usuário e redirecioná-lo para a URL apropriada, conforme especificado na configuração. Além disso, permite salvar o idioma preferido 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 como configurar o matcher.

Passo 5: Definir Rotas de Idioma Dinâmicas

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

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 o idioma adicionando um novo layout em seu diretório [locale]:

import type { Next14LayoutIntlayer } 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}>{children}</body>  </html>);export default LocaleLayout;

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

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

export { generateStaticParams } from "next-intlayer"; // Linha a inserirconst 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 todos os idiomas, 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.

Passo 6: Declarar Seu Conteúdo

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

import { t, type DeclarationContent } from "intlayer";const pageContent = {  key: "page",  content: {    getStarted: {      main: t({        en: "Get started by editing",        fr: "Commencez par éditer",        es: "Comience por editar",      }),      pageLink: "src/app/page.tsx",    },  },} satisfies DeclarationContent;export default pageContent;

Suas declarações de conteúdo podem ser definidas em qualquer lugar da sua aplicação, desde que sejam 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.{ts,tsx,js,jsx,mjs,cjs}). Para mais detalhes, consulte a documentação sobre declaração de conteúdo.

Passo 7: Utilizar Conteúdo em Seu Código

Acesse seus dicionários de conteúdo em toda a sua aplicação:

import { ClientComponentExample } from "@components/ClientComponentExample";import { ServerComponentExample } from "@components/ServerComponentExample";import { type Next14PageIntlayer, IntlayerClientProvider } 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}>        <IntlayerClientProvider locale={locale}>          <ServerComponentExample />          <ClientComponentExample />        </IntlayerClientProvider>      </IntlayerServerProvider>    </>  );};export default Page;

• IntlayerClientProvider é usado para fornecer o idioma aos componentes do lado do cliente. Ele pode ser colocado em qualquer componente pai, incluindo o layout. No entanto, recomenda-se colocá-lo em um layout, pois o Next.js compartilha código de layout entre as páginas, tornando-o mais eficiente. Ao usar 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 o idioma aos filhos do servidor. Ele não pode ser definido no layout.

  O layout e a 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 cache do React), fazendo com que cada “contexto” seja recriado para diferentes segmentos da aplicação. Colocar o provedor em um layout compartilhado quebraria essa isolação, impedindo a correta propagação dos valores de contexto do servidor para seus componentes do servidor.

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

import type { FC } from "react";import { useIntlayer } from "next-intlayer/server";const ServerComponentExample: FC = () => {  const content = useIntlayer("server-component-example"); // Criar 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., deve chamar o valor da função, como:

jsx

<img src={content.image.src.value} alt={content.image.value} />

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

(Opcional) Passo 8: Internacionalização de seus metadados

No caso de 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 getTranslationContent para traduzir seus metadados.

import {  type IConfigLocales,  getTranslationContent,  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>) =>    getTranslationContent(content, locale);  /**   * Gera um objeto contendo todas as URLs para cada idioma.   *   * Exemplo:   * ```ts   *  getMultilingualUrls('/about');   *   *  // Retorna   *  // {   *  //   en: '/about',   *  //   fr: '/fr/about',   *  //   es: '/es/about',   *  // }   * ```   */  const multilingualUrls = getMultilingualUrls("/");  return {    title: t<string>({      en: "My title",      fr: "Mon titre",      es: "Mi título",    }),    description: t({      en: "My description",      fr: "Ma description",      es: "Mi descripción",    }),    alternates: {      canonical: "/",      languages: { ...multilingualUrls, "x-default": "/" },    },    openGraph: {      url: multilingualUrls[locale],    },  };};// ... Resto do código

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

(Opcional) Passo 9: Internacionalização do seu sitemap.xml e robots.txt

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

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;

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.

(Opcional) Passo 10: Alterar o idioma do seu conteúdo

Para mudar o idioma do seu conteúdo, você pode usar a função setLocale fornecida pelo hook useLocale. Esta função permite definir o idioma da aplicação e atualizar o conteúdo de acordo.

"use client";import {  Locales,  getHTMLTextDir,  getLocaleName,  getLocalizedUrl,} from "intlayer";import { useLocale } from "next-intlayer";import { type FC } from "react";const LocaleSwitcher: FC = () => {  const { locale, pathWithoutLocale, availableLocales, setLocale } =    useLocale();  return (    <ol>      {availableLocales.map((localeItem) => (        <li key={localeItem}>          <a            href={getLocalizedUrl(pathWithoutLocale, localeItem)}            hrefLang={localeItem}            aria-current={locale === localeItem ? "page" : undefined}            onClick={(e) => {              e.preventDefault();              setLocale(localeItem);            }}          >            <span>              {/* Idioma em seu próprio idioma - por exemplo, Français */}              {getLocaleName(localeItem, locale)}            </span>            <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>              {/* Idioma no idioma atual - por exemplo, Francés com idioma atual definido para Locales.SPANISH */}              {getLocaleName(localeItem)}            </span>            <span dir="ltr" lang={Locales.ENGLISH}>              {/* Idioma em inglês - por exemplo, francês */}              {getLocaleName(localeItem, Locales.ENGLISH)}            </span>            <span>              {/* Idioma em seu próprio idioma - por exemplo, FR */}              {localeItem}            </span>          </a>        </li>      ))}    </ol>  );};

Referências da documentação:

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

Configurar TypeScript

O Intlayer usa a augmentação de módulos para obter os benefícios do TypeScript e tornar sua base de código mais forte.

Certifique-se de que sua configuração do TypeScript inclua os tipos autogerados.

{  // ... Suas configurações TypeScript existentes  "include": [    // ... Suas configurações TypeScript existentes    "types", // Incluir os tipos auto-gerados  ],}

Configuração do Git

Recomenda-se ignorar os arquivos gerados pelo Intlayer. Isso permite evitar o comprometimento deles em seu repositório Git.

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

# Ignorar os arquivos gerados pelo Intlayer.intlayer