Documentation

Ambiente

Intlayer com Next.js

Começando a internacionalizar (i18n) com Intlayer e Next.js 15 App Router

O que é Intlayer?

Intlayer é uma biblioteca de internacionalização (i18n) inovadora e de código aberto, projetada para simplificar o suporte multilíngue em aplicativos web modernos. O Intlayer se integra perfeitamente ao mais recente framework Next.js 15, incluindo seu poderoso App Router. Ele é otimizado para trabalhar 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 em nível de componente.
Localizar dinamicamente metadados, rotas e conteúdo.
Acessar traduções tanto em componentes do lado do cliente quanto do servidor.
Garantir suporte ao TypeScript com tipos gerados automaticamente, melhorando a autocompletação e a detecção de erros.
Beneficiar-se de recursos avançados, como detecção e troca de localidade dinâmica.

Nota: O Intlayer é compatível com Next.js 12, 13, 14 e 15. Se você estiver usando o Next.js Page Router, consulte este guia. Para Next.js 12, 13, 14 com App Router, consulte este guia.

Guia Passo a Passo para Configurar o Intlayer em um Aplicativo Next.js

Passo 1: Instalar Dependências

Instale os pacotes necessários usando npm:

bash

1npm install intlayer next-intlayer

bash

1yarn add intlayer next-intlayer

bash

1pnpm add intlayer next-intlayer

Passo 2: Configurar Seu Projeto

Crie um arquivo de configuração para configurar os idiomas de seu aplicativo:

typescript

1// intlayer.config.ts
2
3import { Locales, type IntlayerConfig } from "intlayer";
4
5const config: IntlayerConfig = {
6  internationalization: {
7    locales: [
8      Locales.ENGLISH,
9      Locales.FRENCH,
10      Locales.SPANISH,
11      // Seus outros idiomas
12    ],
13    defaultLocale: Locales.ENGLISH,
14  },
15};
16
17export default config;

Para ver todos os parâmetros disponíveis, consulte a documentação de configuração aqui.

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

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

typescript

1// next.config.mjs
2import { withIntlayer } from "next-intlayer/server";
3
4/** @type {import('next').NextConfig} */
5const nextConfig = {};
6
7export default withIntlayer(nextConfig);

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

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

typescript

1// src/middleware.ts
2export { intlayerMiddleware as middleware } from "next-intlayer/middleware";
3
4export const config = {
5  matcher: "/((?!api|static|.*\\..*|_next).*)",
6};

Passo 5: Definir Rotas de Localidade Dinâmica

Implemente roteamento dinâmico para conteúdo localizado:

Mude src/app/page.ts para src/app/[locale]/page.ts

Em seguida, implemente a função generateStaticParams em seu Layout do aplicativo.

tsx

1// src/app/layout.tsx
2
3import type { ReactNode } from "react";
4import "./globals.css";
5
6export { generateStaticParams } from "next-intlayer"; // Linha a inserir
7
8const RootLayout = ({
9  children,
10}: Readonly<{
11  children: ReactNode;
12}>) => children;
13
14export default RootLayout;

Em seguida, adicione um novo layout em seu diretório [locale]:

tsx

1// src/app/[locale]/layout.tsx
2
3import { type NextLayoutIntlayer } from "next-intlayer";
4import { Inter } from "next/font/google";
5import { getHTMLTextDir } from "intlayer";
6
7const inter = Inter({ subsets: ["latin"] });
8
9const LocaleLayout: NextLayoutIntlayer = async ({ children, params }) => {
10  const { locale } = await params;
11  return (
12    <html lang={locale} dir={getHTMLTextDir(locale)}>
13      <body className={inter.className}>{children}</body>
14    </html>
15  );
16};
17
18export default LocaleLayout;

Passo 6: Declarar Seu Conteúdo

Crie e gerencie seus dicionários de conteúdo:

tsx

1// src/app/[locale]/page.content.ts
2import { t, type DeclarationContent } from "intlayer";
3
4const pageContent = {
5  key: "page",
6  content: {
7    getStarted: {
8      main: t({
9        en: "Get started by editing",
10        fr: "Commencez par éditer",
11        es: "Comience por editar",
12      }),
13      pageLink: "src/app/page.tsx",
14    },
15  },
16} satisfies DeclarationContent;
17
18export default pageContent;

Veja como declarar seus arquivos de declaração do Intlayer.

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

Acesse seus dicionários de conteúdo em todo o seu aplicativo:

tsx

1// src/app/[locale]/page.ts
2
3import { ClientComponentExample } from "@component/ClientComponentExample";
4import { LocaleSwitcher } from "@component/LangSwitcherDropDown";
5import { NestedServerComponentExample } from "@component/NestedServerComponentExample";
6import { ServerComponentExample } from "@component/ServerComponentExample";
7import { type NextPageIntlayer, IntlayerClientProvider } from "next-intlayer";
8import { IntlayerServerProvider, useIntlayer } from "next-intlayer/server";
9
10const PageContent = () => {
11  const { title, content } = useIntlayer("page");
12
13  return (
14    <>
15      <p>{content.getStarted.main}</p>
16      <code>{content.getStarted.pageLink}</code>
17    </>
18  );
19};
20
21const Page: NextPageIntlayer = async ({ params }) => {
22  const { locale } = await params;
23
24  return (
25    <>
26      {/**
27       *   IntlayerServerProvider é usado para fornecer a localidade aos filhos do servidor
28       *   Não funciona se definido no layout
29       */}
30      <IntlayerServerProvider locale={locale}>
31        <PageContent />
32        <ServerComponentExample />
33      </IntlayerServerProvider>
34      {/**
35       *   IntlayerClientProvider é usado para fornecer a localidade aos filhos do cliente
36       *   Pode ser definido em qualquer componente pai, incluindo o layout
37       */}
38      <IntlayerClientProvider locale={locale}>
39        <ClientComponentExample />
40      </IntlayerClientProvider>
41    </>
42  );
43};
44
45export default Page;

tsx

1// src/components/ClientComponentExample.tsx
2
3"use client";
4
5import { useIntlayer } from "next-intlayer";
6
7export const ClientComponentExample = () => {
8  const content = useIntlayer("client-component-example"); // Crie a declaração de conteúdo relacionada
9
10  return (
11    <div>
12      <h2>{content.title} </h2>
13      <p>{content.content}</p>
14    </div>
15  );
16};

tsx

1// src/components/ServerComponentExample.tsx
2
3import { useIntlayer } from "next-intlayer/server";
4
5export const ServerComponentExample = () => {
6  const content = useIntlayer("server-component-example"); // Crie a declaração de conteúdo relacionada
7
8  return (
9    <div>
10      <h2>{content.title} </h2>
11      <p>{content.content}</p>
12    </div>
13  );
14};

Nota: 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:
tsx
1<img src={content.image.src.value} alt={content.image.value} />

Para um uso mais detalhado do Intlayer em componentes Cliente ou Servidor, veja o exemplo do Next.js aqui.

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

No caso de você querer internacionalizar seus metadados, como o título de 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.

typescript

1// src/app/[locale]/layout.tsx ou src/app/[locale]/page.tsx
2
3import {
4  type IConfigLocales,
5  getTranslationContent,
6  getMultilingualUrls,
7} from "intlayer";
8import type { Metadata } from "next";
9import type { LocalParams } from "next-intlayer";
10
11export const generateMetadata = ({
12  params: { locale },
13}: LocalParams): Metadata => {
14  const t = <T>(content: IConfigLocales<T>) =>
15    getTranslationContent(content, locale);
16
17  /**
18   * Gera um objeto contendo todas as URLs para cada localidade.
19   *
20   * Exemplo:
21   * ```ts
22   *  getMultilingualUrls('/about');
23   *
24   *  // Retorna
25   *  // {
26   *  //   en: '/about',
27   *  //   fr: '/fr/about',
28   *  //   es: '/es/about',
29   *  // }
30   * ```
31   */
32  const multilingualUrls = getMultilingualUrls("/");
33
34  return {
35    title: t<string>({
36      en: "My title",
37      fr: "Mon titre",
38      es: "Mi título",
39    }),
40    description: t({
41      en: "My description",
42      fr: "Ma description",
43      es: "Mi descripción",
44    }),
45    alternates: {
46      canonical: url,
47      languages: { ...multilingualUrls, "x-default": "/" },
48    },
49    openGraph: {
50      url: multilingualUrls[locale],
51    },
52  };
53};
54
55// ... Restante do código

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

(Opcional) Passo 9: Internacionalização de 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.

tsx

1// src/app/sitemap.ts
2
3import { getMultilingualUrls } from "intlayer";
4import type { MetadataRoute } from "next";
5
6const sitemap = (): MetadataRoute.Sitemap => [
7  {
8    url: "https://example.com",
9    alternates: {
10      languages: getMultilingualUrls("https://example.com"),
11    },
12  },
13  {
14    url: "https://example.com/login",
15    alternates: {
16      languages: getMultilingualUrls("https://example.com/login"),
17    },
18  },
19  {
20    url: "https://example.com/register",
21    alternates: {
22      languages: getMultilingualUrls("https://example.com/register"),
23    },
24  },
25];
26
27export default sitemap;

tsx

1// src/app/robots.ts
2import type { MetadataRoute } from "next";
3import { getMultilingualUrls } from "intlayer";
4
5const getAllMultilingualUrls = (urls: string[]) =>
6  urls.flatMap((url) => Object.values(getMultilingualUrls(url)) as string[]);
7
8const robots = (): MetadataRoute.Robots => ({
9  rules: {
10    userAgent: "*",
11    allow: ["/"],
12    disallow: getAllMultilingualUrls(["/login", "/register"]),
13  },
14  host: "https://example.com",
15  sitemap: `https://example.com/sitemap.xml`,
16});
17
18export 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: Mudar 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. Essa função permite que você defina a localidade do aplicativo e atualize o conteúdo de acordo.

tsx

1import { Locales } from "intlayer";
2import { useLocale } from "next-intlayer";
3
4const MyComponent = () => {
5  const { setLocale } = useLocale();
6
7  return (
8    <button onClick={() => setLocale(Locales.English)}>Alterar Idioma</button>
9  );
10};

Configurar TypeScript

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

alt text

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

json5

1// tsconfig.json
2
3{
4  // sua configuração personalizada
5  include: [
6    "src",
7    "types", // <- Inclua os tipos gerados automaticamente
8  ],
9}

Configuração do Git

É recomendado 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:

gitignore

1# Ignore os arquivos gerados pelo Intlayer
2.intlayer

Se você tiver uma ideia para melhorar esta documentação, sinta-se à vontade para contribuir enviando uma pull request no GitHub.

Link do GitHub para a documentação

Busca de função Next.js 14 e App Router

Começando a internacionalizar (i18n) com Intlayer e Next.js 15 App Router

O que é Intlayer?

Guia Passo a Passo para Configurar o Intlayer em um Aplicativo Next.js

Passo 1: Instalar Dependências

Passo 2: Configurar Seu Projeto

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

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

Passo 5: Definir Rotas de Localidade Dinâmica

Passo 6: Declarar Seu Conteúdo

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

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

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

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

Configurar TypeScript

Configuração do Git

Nesta página