Receba notificações sobre os próximos lançamentos de Intlayer
    Criação:2024-12-06Última atualização:2025-06-29

    Traduza seu Next.js 15 com Intlayer | Internacionalização (i18n)

    Veja o Modelo de Aplicação no GitHub.

    O que é o Intlayer?

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

    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.
    • Acessar traduções tanto em componentes do lado do cliente quanto do lado do servidor.
    • Garantir suporte ao TypeScript com tipos gerados automaticamente, melhorando o autocompletar e a detecção de erros.
    • Beneficie de recursos avançados, como detecção e troca dinâmica de localidade.
    O Intlayer é compatível com Next.js 12, 13, 14 e 15. Se você estiver usando o Next.js Page Router, pode consultar este guia. Para Next.js 12, 13, 14 com App Router, 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çã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, bem como middleware para detectar o idioma preferido do usuário, gerenciar cookies e lidar com redirecionamento de URL.

    Passo 2: Configure Seu Projeto

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

    intlayer.config.ts
    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 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.

    Passo 3: Integre o Intlayer na sua Configuração Next.js

    Configure seu setup Next.js para usar o Intlayer:

    next.config.ts
    import type { NextConfig } from "next";import { withIntlayer } from "next-intlayer/server";const nextConfig: NextConfig = {  /* opções de configuração aqui */};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 assegura compatibilidade com componentes de servidor.

    Passo 4: Definir Rotas Dinâmicas de Locale

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

    src/app/layout.tsx
    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 locale adicionando um novo layout no seu diretório [locale]:

    src/app/[locale]/layout.tsx
    import type { NextLayoutIntlayer } from "next-intlayer";import { Inter } from "next/font/google";import { getHTMLTextDir } from "intlayer";const inter = Inter({ subsets: ["latin"] });const LocaleLayout: NextLayoutIntlayer = async ({ children, params }) => {  const { locale } = await params;  return (    <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 locale. Exemplo: /en-US/about se referirá a en-US e /fr/about a fr.
    Nesta etapa, você encontrará o erro: Error: Missing <html> and <body> tags in the root layout.. 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 via caminhos como /en, /fr, /es no seu navegador. Para definir o locale padrão como a página raiz, consulte a configuração do middleware no passo 7.

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

    src/app/[locale]/layout.tsx
    export { generateStaticParams } from "next-intlayer"; // Linha a inserirconst LocaleLayout: NextLayoutIntlayer = async ({ children, params }) => {  /*... Resto do código*/};export default LocaleLayout;
    generateStaticParams garante que sua aplicação pré-construa as páginas necessárias para todos os locais, reduzindo o cálculo 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 5: Declare Seu Conteúdo

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

    src/app/[locale]/page.content.ts
    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",      }),      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,mjx,cjs,cjx}).
    Para mais detalhes, consulte a documentação de declaração de conteúdo.

    Passo 6: 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
    import type { FC } from "react";import { ClientComponentExample } from "@components/ClientComponentExample";import { ServerComponentExample } from "@components/ServerComponentExample";import { type NextPageIntlayer, IntlayerClientProvider } from "next-intlayer";import { IntlayerServerProvider, useIntlayer } from "next-intlayer/server";const PageContent: FC = () => {  const content = useIntlayer("page");  return (    <>      <p>{content.getStarted.main}</p>      <code>{content.getStarted.pageLink}</code>    </>  );};const Page: NextPageIntlayer = async ({ params }) => {  const { locale } = await params;  return (    <IntlayerServerProvider locale={locale}>      <PageContent />      <ServerComponentExample />      <IntlayerClientProvider locale={locale}>        <ClientComponentExample />      </IntlayerClientProvider>    </IntlayerServerProvider>  );};export default Page;
    • IntlayerClientProvider é usado para fornecer a localidade 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 porque o Next.js compartilha o código do layout entre as páginas, tornando-o mais eficiente. Ao usar o 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 aos filhos do servidor. Ele não pode ser definido 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 requisição (via mecanismo de cache do React), fazendo com que cada "contexto" seja recriado para diferentes segmentos da aplicação. Colocar o provider em um layout compartilhado quebraria esse isolamento, impedindo a propagação correta dos valores do contexto do servidor para seus componentes de servidor.
    src/components/ClientComponentExample.tsx
    "use client";import type { FC } from "react";import { useIntlayer } from "next-intlayer";export const ClientComponentExample: FC = () => {  const content = useIntlayer("client-component-example"); // Criar declaração de conteúdo relacionado  return (    <div>      <h2>{content.title}</h2>      <p>{content.content}</p>    </div>  );};
    src/components/ServerComponentExample.tsx
    import type { FC } from "react";import { useIntlayer } from "next-intlayer/server";export const ServerComponentExample: FC = () => {  const content = useIntlayer("server-component-example"); // Criar declaração de conteúdo relacionado  return (    <div>      <h2>{content.title}</h2>      <p>{content.content}</p>    </div>  );};
    Se você quiser usar seu conteúdo em um atributo do tipo string, como alt, title, href, aria-label, etc., você deve chamar o valor da função, assim:
    <img src={content.image.src.value} alt={content.image.value} />
    Para saber mais sobre o hook useIntlayer, consulte a documentação.

    (Opcional) Passo 7: Configurar Middleware para Detecção de Localidade

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

    src/middleware.ts
    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.

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

    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 dela, você pode recuperar o conteúdo da função getIntlayer para traduzir seus metadados.

    src/app/[locale]/metadata.content.ts
    import { type Dictionary, t } from "intlayer";import { 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/app/[locale]/layout.tsx or src/app/[locale]/page.tsx
    import { getIntlayer, getMultilingualUrls } from "intlayer";import type { Metadata } from "next";import type { LocalPromiseParams } from "next-intlayer";export const generateMetadata = async ({  params,}: LocalPromiseParams): Promise<Metadata> => {  const { locale } = await params;  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 {    ...metadata,    alternates: {      canonical: multilingualUrls[locale as keyof typeof multilingualUrls],      languages: { ...multilingualUrls, "x-default": "/" },    },    openGraph: {      url: multilingualUrls[locale],    },  };};// ... Resto do código
    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.

    Alternativamente, você pode usar a função getTranslation para declarar seus metadados. No entanto, recomenda-se usar arquivos de declaração de conteúdo para automatizar a tradução dos seus metadados e externalizar o conteúdo em algum momento.

    src/app/[locale]/layout.tsx or src/app/[locale]/page.tsx
    import {  type IConfigLocales,  getTranslation,  getMultilingualUrls,} from "intlayer";import type { Metadata } from "next";import type { LocalPromiseParams } from "next-intlayer";export const generateMetadata = async ({  params,}: LocalPromiseParams): Promise<Metadata> => {  const { locale } = await params;  const t = <T>(content: IConfigLocales<T>) => getTranslation(content, locale);  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",    }),  };};// ... 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 seu sitemap.

    src/app/sitemap.ts
    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
    import type { MetadataRoute } from "next";import { getMultilingualUrls } from "intlayer";// Obtém todas as URLs multilíngues a partir de uma lista de URLsconst getAllMultilingualUrls = (urls: string[]) =>  urls.flatMap((url) => Object.values(getMultilingualUrls(url)) as string[]);// Configuração do arquivo robots.txt com regras para rastreadoresconst robots = (): MetadataRoute.Robots => ({  rules: {    userAgent: "*",    allow: ["/"],    disallow: getAllMultilingualUrls(["/login", "/register"]), // Bloqueia páginas de login e registro  },  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 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/LocaleSwitcher.tsx
    "use client";import type { FC } from "react";import {  Locales,  getHTMLTextDir,  getLocaleName,  getLocalizedUrl,} from "intlayer";import { useLocale } from "next-intlayer";import Link from "next/link";export const LocaleSwitcher: FC = () => {  const { locale, pathWithoutLocale, availableLocales } = useLocale();  const { setLocaleCookie } = useLocaleCookie();  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={() => setLocaleCookie(localeItem)}          >            <span>              {/* Local - ex. FR */}              {localeItem}            </span>            <span>              {/* Idioma no seu próprio Local - ex. Français */}              {getLocaleName(localeItem, locale)}            </span>            <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>              {/* Idioma no Local atual - ex. Francés com o local atual definido 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. Essa função não permitirá o pré-carregamento da página e recarregará a página.
    Nesse caso, sem redirecionamento usando router.push, apenas o seu código do lado do servidor mudará o idioma do conteúdo.
    src/components/LocaleSwitcher.tsx
    "use client";import { useRouter } from "next/navigation";import { useLocale } from "next-intlayer";import { getLocalizedUrl } from "intlayer";// ... Resto do códigoconst router = useRouter();const { setLocale } = useLocale({  onLocaleChange: (locale) => {    router.push(getLocalizedUrl(pathWithoutLocale, locale));  },});return (  <button onClick={() => setLocale(Locales.FRENCH)}>Mudar para Francês</button>);

    Referências da documentação:

    (Opcional) Passo 11: 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 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 no idioma de sua preferência.
    • 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 sua base de 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
    "use client";import { getLocalizedUrl } from "intlayer";import NextLink, { type LinkProps as NextLinkProps } from "next/link";import { useLocale } from "next-intlayer";import type { PropsWithChildren, FC } from "react";/** * Função utilitária para verificar se uma URL dada é 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 no idioma atual. * Para links internos, ele usa `getLocalizedUrl` para prefixar a URL com o idioma (ex: /fr/about). * Isso garante que a navegação permaneça dentro do mesmo contexto de idioma. */export const Link: FC<PropsWithChildren<NextLinkProps>> = ({  href,  children,  ...props}) => {  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} {...props}>      {children}    </NextLink>  );};

    Como Funciona

    • Detectando 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 o 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 se beneficiar de uma melhor SEO e usabilidade.

    (Opcional) Passo 12: Otimize o tamanho do seu bundle

    Ao usar o 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 habilitar essa otimização, instale o pacote @intlayer/swc. Uma vez instalado, o next-intlayer detectará e usará automaticamente o plugin:

    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.

    Autocompletion

    Translation error

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

    tsconfig.json
    {  // ... Suas configurações existentes do TypeScript  "include": [    // ... Suas configurações existentes do TypeScript    ".intlayer/**/*.ts", // Incluir os tipos gerados automaticamente  ],}

    Configuração do Git

    É recomendado ignorar os arquivos gerados pelo Intlayer. Isso permite evitar que eles sejam commitados no seu repositório Git.

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

    .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 do Intlayer para VS Code.

    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.

    Ir Além

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

    Histórico do Documento

    • 5.5.10 - 2025-06-29: Histórico inicial
    Testes
    Next.js 14 e App Router
    Receba notificações sobre os próximos lançamentos de Intlayer