Creation:2024-12-06Last update:2026-05-31

    Traduza seu site Next.js 16 usando Intlayer | Internacionalização (i18n)

    www.youtube.com

    Veja o Modelo de Aplicação no GitHub.

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

    O Intlayer é otimizado para funcionar com Componentes de servidor para renderização eficiente e é totalmente compatível com Turbopack. Ele não bloqueia a renderização estática e oferece middleware, bem como todos os recursos necessários para dimensionar a internacionalização (i18n).

    Intlayer é compatível com Next.js 12, 13, 14, 15 e 16. Se você estiver usando o roteador de páginas Next.js, pode consultar este [guia] (/pt/doc/environment/nextjs/next-with-page-router). O roteamento por locale é útil para SEO, tamanho do bundle e desempenho. Se não precisar dele, você pode consultar este guia. Para Next.js 12, 13, 14 e 15 com o App Router, consulte este guia.

    Em vez de carregar arquivos JSON enormes em suas páginas, carregue apenas o conteúdo necessário. O Intlayer ajuda a reduzir o tamanho do bundle e das páginas em até 50%.

    Definir o escopo do conteúdo do seu aplicativo facilita a manutenção de aplicativos de grande escala. Você pode duplicar ou excluir uma única pasta de recursos sem o fardo mental de revisar toda a base de código de seu conteúdo. Além disso, o Intlayer é totalmente tipado (fully typed) para garantir a precisão do seu conteúdo.

    A co-localização de conteúdo reduz o contexto necessário pelos Large Language Models (LLMs). O Intlayer também vem com um conjunto de ferramentas, como uma CLI para testar traduções ausentes,LSP, MCP, e habilidades do agente, para tornar a experiência do desenvolvedor (DX) ainda mais tranquila para os agentes de IA.

    Use a automação para traduzir seu pipeline de CI/CD usando o LLM de sua escolha às custas de seu provedor de IA. O Intlayer também oferece um compilador para automatizar a extração de conteúdo, bem como uma plataforma web para ajudar a traduzir em segundo plano.

    Conectar arquivos JSON enormes a componentes pode levar a problemas de desempenho e reatividade. O Intlayer otimiza o carregamento do seu conteúdo no momento da construção.

    Mais do que apenas uma solução i18n, o Intlayer fornece um [editor visual] auto-hospedado(/pt/doc/concept/editor) e um CMS completo para ajudá-lo a gerenciar seu conteúdo multilíngue em tempo real, facilitando a colaboração com tradutores, redatores e outros membros da equipe. O conteúdo pode ser armazenado local e/ou remotamente.

    Guia passo a passo para configurar o Intlayer em uma aplicação Next.js

    1. Instalar dependências

      Instale os pacotes necessários usando npm:

      bash
      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, transpiração e comandos CLI.

      • next-intlayer

        O pacote que integra o Intlayer com 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 um proxy para detectar o idioma preferido do usuário, gerenciar cookies e lidar com redirecionamento de URL.

    2. Configure Seu Projeto

      Aqui está a estrutura final que criaremos:

      bash
      .├── src│   ├── app│   │   ├── [locale]│   │   │   ├── layout.tsx            # Layout de localidade para o provedor Intlayer│   │   │   ├── page.content.ts│   │   │   └── page.tsx│   │   └── layout.tsx                # Layout raiz para estilos e provedores globais│   ├── components│   │   ├── client-component-example.content.ts│   │   ├── ClientComponentExample.tsx│   │   ├── LocaleSwitcher│   │   │   ├── localeSwitcher.content.ts│   │   │   └── LocaleSwitcher.tsx│   │   ├── server-component-example.content.ts│   │   └── ServerComponentExample.tsx│   └── proxy.ts├── intlayer.config.ts├── next.config.ts├── package.json└── tsconfig.json
      Se você não deseja roteamento de localidade, o intlayer pode ser usado como um simples provedor / hook. Veja este guia para mais detalhes.

      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 proxy, 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. 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 garante compatibilidade com componentes do servidor.

      A função withIntlayer() é uma função do tipo promise. Ela permite preparar os dicionários do Intlayer antes do início da build. Se você quiser usá-la com outros plugins, pode usar await. Exemplo:

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

      Se quiser usá-lo de forma síncrona, pode usar a função withIntlayerSync(). Exemplo:

      ts
      const nextConfig = withIntlayerSync(nextConfig);const nextConfigWithOtherPlugins = withOtherPlugins(nextConfig);export default nextConfigWithOtherPlugins;

      Intlayer detecta automaticamente se o seu projeto está a usar webpack ou Turbopack com base nas flags de linha de comando --webpack, --turbo, ou --turbopack, bem como na sua versão do Next.js atual.

      Desde next>=16, se estiver a usar Rspack, deve forçar explicitamente o Intlayer a usar a configuração do webpack, desativando o Turbopack:

      ts
      withRspack(withIntlayer(nextConfig, { enableTurbopack: false }));

    4. Definir Rotas Dinâmicas de Localidade

      Remova tudo de 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 }) => (
  // Você ainda pode envolver os filhos com outros provedores, como `next-themes`, `react-query`, `framer-motion`, etc.
  <>{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
      import { type NextLayoutIntlayer, IntlayerClientProvider } 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}>
        <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 fase, 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 a localidade padrão como a página raiz, consulte a configuração do proxy no passo 7.

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

      src/app/[locale]/layout.tsx
      export { generateStaticParams } from "next-intlayer"; // Linha a inserir

const 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 todas as localidades, 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.
      O Intlayer funciona com export const dynamic = 'force-static'; para garantir que as páginas sejam pré-construídas para todas as localidades.

    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,cjs,md,mdx,yaml,yml}).
      Para mais detalhes, consulte a documentação de declaração de conteúdo.

    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 } 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 />

      <ClientComponentExample />
    </IntlayerServerProvider>
  );
};

export default Page;
      • IntlayerClientProvider é usado para fornecer a localidade para componentes do lado do cliente. 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 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 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 provedor 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 relacionada

  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 relacionada

  return (
    <div>
      <h2>{content.title}</h2>
      <p>{content.content}</p>
    </div>
  );
};
      Se quiser usar seu conteúdo em um atributo string, como alt, title, href, aria-label, etc., você deve chamar o valor da função, assim:
      html
      <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.
      Se a sua aplicação já existe, você pode usar o Intlayer Compiler em conjunto com o comando extract para converter milhares de componentes em um segundo.

    7. Configurar Proxy para Detecção de Localidade

      Opcional

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

      src/proxy.ts
      export { intlayerProxy as proxy } from "next-intlayer/proxy";

export const config = {
  matcher:
    "/((?!api|static|assets|robots|sitemap|sw|service-worker|manifest|.*\\..*|_next).*)",
};
      O intlayerProxy é 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.
      Se você precisar encadear vários proxies juntos (por exemplo, intlayerProxy com autenticação ou proxies personalizados), o Intlayer agora fornece um auxiliar chamado multipleProxies.
      ts
      import { multipleProxies, intlayerProxy } from "next-intlayer/proxy";import { customProxy } from "@utils/customProxy";export const proxy = multipleProxies([intlayerProxy, customProxy]);

    8. Internacionalização dos seus metadados

      Opcional

      Caso queira 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("/");
  const localizedUrl =
    multilingualUrls[locale as keyof typeof multilingualUrls];

  return {
    ...metadata,
    alternates: {
      canonical: localizedUrl,
      languages: { ...multilingualUrls, "x-default": "/" },
    },
    openGraph: {
      url: localizedUrl,
    },
  };
};

// ... 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, é recomendável 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.

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

      Opcional

      Para internacionalizar o 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 o 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"),
        "x-default": "https://example.com",
      },
    },
  },
  {
    url: "https://example.com/login",
    alternates: {
      languages: {
        ...getMultilingualUrls("https://example.com/login"),
        "x-default": "https://example.com/login",
      },
    },
  },
  {
    url: "https://example.com/register",
    alternates: {
      languages: {
        ...getMultilingualUrls("https://example.com/register"),
        "x-default": "https://example.com/register",
      },
    },
  },
];

export default sitemap;
      src/app/robots.ts
      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. 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/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, setLocale } =
    useLocale();

  return (
    <div>
      <button popoverTarget="localePopover">{getLocaleName(locale)}</button>
      <div id="localePopover" popover="auto">
        {availableLocales.map((localeItem) => (
          <Link
            href={getLocalizedUrl(pathWithoutLocale, localeItem)}
            key={localeItem}
            aria-current={locale === localeItem ? "page" : undefined}
            onClick={() => setLocale(localeItem)}
            replace // Garantirá que o botão "voltar" do navegador redirecione para a página anterior
          >
            <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. Veja a documentação do hook useLocale para mais detalhes.
      Você também pode definir uma função na opção onLocaleChange para disparar uma função personalizada quando o idioma for alterado.
      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:

    11. 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 Link personalizado. Esse 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.
      • Manutenibilidade: 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 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, 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: 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, obtém 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 não são alterados 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 o usuário estiver em francês, passar /about como href o 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 sua aplicação, você mantém uma experiência de usuário coerente e consciente do idioma, além de se beneficiar de melhor SEO e usabilidade.

    12. Obter a localidade atual em Server Actions

      Opcional

      Se você precisar da localidade ativa dentro de uma Server Action (ex: para localizar e-mails ou executar lógica baseada em localidade), chame getLocale de next-intlayer/server:

      src/app/actions/getLocale.ts
      "use server";import { getLocale } from "next-intlayer/server";export const myServerAction = async () => {  const locale = await getLocale();  // Fazer algo com a localidade};

      A função getLocale segue uma estratégia em cascata para determinar a localidade do usuário:

      1. Primeiro, verifica os cabeçalhos da requisição para um valor de localidade que possa ter sido definido pelo proxy.
      2. Se nenhuma localidade for encontrada nos cabeçalhos, procura por uma localidade armazenada em cookies.
      3. Se nenhum cookie for encontrado, tenta detectar o idioma preferido do usuário nas configurações do navegador.
      4. Como último recurso, recorre à localidade padrão configurada na aplicação.

      Isso garante que a localidade mais apropriada seja selecionada com base no contexto disponível.

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

      bash
      npm install @intlayer/swc --save-dev
      Nota: Esta otimização está disponível apenas para Next.js 13 e superior.
      Nota: Este pacote não é instalado por padrão porque os plugins SWC ainda são experimentais no Next.js. Pode mudar no futuro.

      Nota: Se você definir a opção como importMode: 'dynamic' ou importMode: 'fetch' (na configuração do dictionary), ela dependerá do Suspense, portanto você terá que envolver suas chamadas useIntlayer em uma fronteira Suspense. Isso significa que você não poderá usar o useIntlayer diretamente no nível superior do seu componente Page / Layout.

    14. Extrair o conteúdo dos seus componentes

      Opcional

      Se você tiver uma base de código existente, transformar milhares de arquivos pode ser demorado.

      Para facilitar esse processo, o Intlayer propõe um compilador / extrator para transformar seus componentes e extrair o conteúdo.

      Para configurá-lo, você pode adicionar uma seção compiler no seu arquivo intlayer.config.ts:

      intlayer.config.ts
      import { type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  // ... Resto da sua configuração
  compiler: {
    /**
     * Indica se o compilador deve ser ativado.
     */
    enabled: true,

    /**
     * Define o caminho dos arquivos de saída
     */
    output: ({ fileName, extension }) => `./${fileName}${extension}`,

    /**
     * Indica se os componentes devem ser salvos após serem transformados. Dessa forma, o compilador pode ser executado apenas uma vez para transformar o aplicativo e depois removido.
     */
    saveComponents: false,

    /**
     * Prefixo da chave do dicionário
     */
    dictionaryKeyPrefix: "",
  },
};

export default config;

      Execute o extrator para transformar seus componentes e extrair o conteúdo

      bash
      npx intlayer extract

    Monitorar mudanças de dicionários no Turbopack

    Ao usar o Turbopack como servidor de desenvolvimento com o comando next dev, as mudanças nos dicionários não serão detectadas automaticamente por padrão.

    Esta limitação ocorre porque o Turbopack não consegue executar plugins do webpack em paralelo para monitorar mudanças nos seus arquivos de conteúdo. Para contornar isso, você precisará usar o comando intlayer watch para executar o servidor de desenvolvimento e o observador de build do Intlayer simultaneamente.

    package.json
    {  // ... Suas configurações existentes do package.json  "scripts": {    // ... Suas configurações de scripts existentes    "dev": "intlayer watch --with 'next dev'",  },}
    Se estiver a usar next-intlayer@<=6.x.x, deve manter a flag --turbopack para que a aplicação Next.js 16 funcione corretamente com o Turbopack. Recomendamos usar next-intlayer@>=7.x.x para evitar esta limitação.

    Configurar TypeScript

    O Intlayer usa aumento de módulo para obter benefícios do TypeScript e tornar seu código mais robusto.

    Autocompletion

    Erro de tradução

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

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

    Configuração do Git

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

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

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

    Instalar a partir do VS Code Marketplace

    Esta extensão oferece:

    • Autocompletação para chaves de tradução.
    • Detecção de erros em tempo real para traduções ausentes.
    • Pré-visualizações in-line de 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 do 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.

    Otimização de bundle
    Next.js 14 e App Router