Traduza seu site Next.js 16 (sem [locale] no caminho da página) usando Intlayer | Internacionalização (i18n)

Veja o Modelo de Aplicação no GitHub.

Índice

O que é o Intlayer?

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

Com o Intlayer, pode:

• Gerir traduções facilmente usando dicionários declarativos ao nível do componente.
• Localizar dinamicamente metadados, rotas e conteúdo.
• Aceder a traduções tanto em componentes client-side como server-side.
• Garantir suporte a TypeScript com tipos gerados automaticamente, melhorando a autocompletação e a detecção de erros.
• Aproveite recursos avançados, como detecção e troca dinâmica de locale.

O Intlayer é compatível com Next.js 12, 13, 14 e 16. Se estiver a usar o Page Router do Next.js, pode consultar este guia. Para Next.js 12, 13, 14 com App Router, consulte este guia.

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

Passo 1: Instalar dependências

Instale os pacotes necessários usando npm:

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

• next-intlayer

O pacote que integra o Intlayer com o Next.js. Fornece providers de contexto e hooks para internacionalização no Next.js. Além disso, inclui o plugin do Next.js para integrar o Intlayer com o Webpack ou o Turbopack, bem como um proxy para detectar a locale preferida do utilizador, gerir cookies e tratar redirecionamentos de URL.

Passo 2: Configure o seu projeto

Aqui está a estrutura final que iremos criar:

.├── src│   ├── app│   │   ├── layout.tsx│   │   ├── page.content.ts│   │   └── page.tsx│   ├── components│   │   ├── clientComponentExample│   │   │   ├── client-component-example.content.ts│   │   │   └── ClientComponentExample.tsx│   │   ├── localeSwitcher│   │   │   ├── localeSwitcher.content.ts│   │   │   └── LocaleSwitcher.tsx│   │   └── serverComponentExample│   │       ├── server-component-example.content.ts│   │       └── ServerComponentExample.tsx│   └── proxy.ts├── intlayer.config.ts├── next.config.ts├── package.json└── tsconfig.json

Se não quiser roteamento por locale, o intlayer pode ser usado apenas como um provider / hook. Veja este guia para mais detalhes.

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

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [      Locales.ENGLISH,      Locales.FRENCH,      Locales.SPANISH,      // Outros locales    ],    defaultLocale: Locales.ENGLISH,  },  routing: {    mode: "search-params", // ou `no-prefix` - Útil para detecção no middleware  },};export default config;

Através deste arquivo de configuração, você pode configurar URLs localizadas, redirecionamento por proxy, nomes de cookies, a localização e extensão das suas declarações de conteúdo, desativar os 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: Integrar o Intlayer na sua configuração do Next.js

Configure seu setup do Next.js para usar o Intlayer:

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 Next.js withIntlayer() é usado para integrar o Intlayer com o Next.js. Ele garante a geração dos ficheiros de declaração de conteúdo e os monitora em modo de desenvolvimento. Define as variáveis de ambiente do Intlayer nos ambientes do Webpack ou Turbopack. Além disso, fornece aliases para otimizar o desempenho e assegura compatibilidade com server components.

A função withIntlayer() é uma função que retorna uma promise. Permite preparar os dicionários do intlayer antes do início do build. Se quiser utilizá-la com outros plugins, pode fazer await. Exemplo:

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

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

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

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

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

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

Passo 4: Definir rotas de localidade dinâmicas

Remova tudo de RootLayout e substitua pelo código a seguir:

import type { Metadata } from "next";import type { ReactNode } from "react";import "./globals.css";import { IntlayerClientProvider, LocalPromiseParams } from "next-intlayer";import { getHTMLTextDir, getIntlayer } from "intlayer";import { getLocale } from "next-intlayer/server";export { generateStaticParams } from "next-intlayer";export const generateMetadata = async ({  params,}: LocalPromiseParams): Promise<Metadata> => {  const { locale } = await params;  const { title, description, keywords } = getIntlayer("metadata", locale);  return {    title,    description,    keywords,  };};const RootLayout = async ({  children,}: Readonly<{  children: ReactNode;}>) => {  const locale = await getLocale();  return (    <html lang={locale} dir={getHTMLTextDir(locale)}>      <IntlayerClientProvider defaultLocale={locale}>        <body>{children}</body>      </IntlayerClientProvider>    </html>  );};export default RootLayout;

Passo 5: Declarar o seu conteúdo

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

import { t, type Dictionary } from "intlayer";import { Metadata } from "next";const metadataContent = {  key: "metadata",  content: {    title: t({      pt: "Meu Título do Projeto",      en: "My Project Title",      fr: "Le Titre de mon Projet",      es: "El Título de mi Proyecto",    }),    description: t({      pt: "Descubra a nossa plataforma inovadora projetada para simplificar o seu fluxo de trabalho e aumentar a sua produtividade.",      en: "Discover our innovative platform designed to streamline your workflow and boost productivity.",      fr: "Découvrez notre plateforme innovante conçue pour simplifier votre flux de travail et booster votre productivité.",      es: "Descubra nuestra plataforma innovadora diseñada para simplificar su flujo de trabajo y aumentar su productividad.",    }),    keywords: t({      pt: ["inovação", "produtividade", "fluxo de trabalho", "SaaS"],      en: ["innovation", "productivity", "workflow", "SaaS"],      pt: ["inovação", "produtividade", "fluxo de trabalho", "SaaS"],      fr: ["innovation", "productivité", "flux de travail", "SaaS"],      es: ["innovación", "productividad", "flujo de trabajo", "SaaS"],    }),  },} as Dictionary<Metadata>;export default metadataContent;

import { t, type Dictionary } from "intlayer";/** @type {import('intlayer').Dictionary<import('next').Metadata>} */const metadataContent = {  key: "metadata",  content: {    title: t({      en: "My Project Title",      fr: "Le Titre de mon Projet",      es: "El Título de mi Proyecto",    }),    description: t({      pt: "Descubra a nossa plataforma inovadora projetada para simplificar o seu fluxo de trabalho e aumentar a produtividade.",      en: "Discover our innovative platform designed to streamline your workflow and boost productivity.",      pt: "Descubra a nossa plataforma inovadora projetada para simplificar o seu fluxo de trabalho e aumentar a produtividade.",      fr: "Découvrez notre plateforme innovante conçue pour simplifier votre flux de travail et booster votre productivité.",      es: "Descubra su plataforma innovadora diseñada para simplificar su flujo de trabajo y aumentar su productividad.",    }),    keywords: t({      pt: ["inovação", "produtividade", "fluxo de trabalho", "SaaS"],      en: ["innovation", "productivity", "workflow", "SaaS"],      fr: ["innovation", "productivité", "flux de travail", "SaaS"],      es: ["innovación", "productividad", "flujo de trabajo", "SaaS"],    }),  },};export default metadataContent;

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

As 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 que correspondam à extensão de ficheiro 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: Utilizar Conteúdo no Seu Código

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

import type { FC } from "react";import { ClientComponentExample } from "@components/clientComponentExample/ClientComponentExample";import { ServerComponentExample } from "@components/serverComponentExample/ServerComponentExample";import {  IntlayerServerProvider,  useIntlayer,  getLocale,} from "next-intlayer/server";import { NextPage } from "next";import { headers, cookies } from "next/headers";const PageContent: FC = () => {  const content = useIntlayer("page");  return (    <>      <p>{content.getStarted.main}</p>      <code>{content.getStarted.pageLink}</code>    </>  );};const Page: NextPage = async () => {  const locale = await getLocale();  return (    <IntlayerServerProvider locale={locale}>      <PageContent />      <ServerComponentExample />      <ClientComponentExample />    </IntlayerServerProvider>  );};export default Page;

• IntlayerClientProvider é usado para fornecer a locale aos componentes do lado do cliente. Pode ser colocado em qualquer componente pai, incluindo o layout. No entanto, recomenda-se colocá-lo no layout porque o Next.js compartilha o código do layout entre 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 o locale aos filhos do servidor. 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 de servidor baseia-se num armazenamento de dados por requisição (via cache do React), fazendo com que cada "context" seja recriado para diferentes segmentos da aplicação. Colocar o provider num layout partilhado quebraria esse isolamento, impedindo a propagação correta dos valores do contexto de servidor para os seus componentes de servidor.

"use client";import type { FC } from "react";import { useIntlayer } from "next-intlayer";export const ClientComponentExample: FC = () => {  const content = useIntlayer("client-component-example"); // Cria a 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";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 o seu conteúdo num atributo string, como alt, title, href, aria-label, etc., deve chamar o valor da função, por exemplo:

<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 Proxy para Detecção de Locale

Configure o proxy para detetar a locale preferida do usuário:

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 precisar encadear vários proxies juntos (por exemplo, intlayerProxy com autenticação ou proxies customizados), o Intlayer agora fornece um helper chamado multipleProxies.

import { multipleProxies, intlayerProxy } from "next-intlayer/proxy";import { customProxy } from "@utils/customProxy";export const proxy = multipleProxies([intlayerProxy, customProxy]);

(Opcional) Passo 8: 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 utilizadores para a página localizada apropriada. O componente Link permite o prefetch da página, o que ajuda a evitar um recarregamento completo.

"use client";import type { FC } from "react";import { Locales, getHTMLTextDir, getLocaleName } from "intlayer";import { useLocale } from "next-intlayer";export const LocaleSwitcher: FC = () => {  const { locale, availableLocales, setLocale } = useLocale({    onChange: () => window.location.reload(),  });  return (    <div>      <button popoverTarget="localePopover">{getLocaleName(locale)}</button>      <div id="localePopover" popover="auto">        {availableLocales.map((localeItem) => (          <button            key={localeItem}            aria-current={locale === localeItem ? "page" : undefined}            onClick={() => setLocale(localeItem)}          >            <span>              {/* Locale — ex.: FR */}              {localeItem}            </span>            <span>              {/* Idioma em seu próprio locale — ex.: Français */}              {getLocaleName(localeItem, locale)}            </span>            <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>              {/* Idioma no locale atual — ex.: Francés com o locale atual definido para Locales.SPANISH */}              {getLocaleName(localeItem)}            </span>            <span dir="ltr" lang={Locales.ENGLISH}>              {/* Idioma em inglês - ex.: Francês */}              {getLocaleName(localeItem, Locales.ENGLISH)}            </span>          </button>        ))}      </div>    </div>  );};

Uma forma alternativa é usar a função setLocale fornecida pelo hook useLocale. Essa função não permitirá o prefetch da página. Consulte a documentação do hook useLocale para mais detalhes.

Referências da documentação:

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

(Opcional) Passo 9: Obter a locale atual em Server Actions

Se precisar da locale ativa dentro de uma Server Action (por exemplo, para localizar e-mails ou executar lógica dependente da locale), chame getLocale de next-intlayer/server:

"use server";import { getLocale } from "next-intlayer/server";export const myServerAction = async () => {  const locale = await getLocale();  // Faça algo com o locale};

A função getLocale segue uma estratégia em cascata para determinar a locale do utilizador:

1. Primeiro, verifica os cabeçalhos da requisição à procura de um valor de locale que pode ter sido definido pelo proxy
2. Se nenhum locale for encontrado nos cabeçalhos, procura um locale armazenado em cookies
3. Se nenhum cookie for encontrado, tenta detetar a língua preferida do utilizador a partir das definições do navegador
4. Como último recurso, recorre ao locale predefinido configurado na aplicação

Isso garante que o idioma mais apropriado seja selecionado com base no contexto disponível.

(Opcional) Passo 10: Otimize o tamanho do bundle

Quando 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 chamadas a 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-devnpx intlayer init

Observação: Esta otimização está disponível apenas para Next.js 13 e versões superiores.

Observação: Este pacote não é instalado por padrão porque plugins SWC ainda são experimentais no Next.js. Isso pode mudar no futuro.

Observação: Se você definir a opção como importMode: 'dynamic' ou importMode: 'live', ela dependerá de Suspense, portanto você terá que envolver suas chamadas useIntlayer em um limite Suspense. Isso significa que você não poderá usar useIntlayer diretamente no nível superior do seu componente Page/Layout.

Monitorar mudanças nos dicionários com Turbopack

Quando estiver a usar o Turbopack como servidor de desenvolvimento com o comando next dev, as alterações nos dicionários não serão detetadas automaticamente por padrão.

Esta limitação ocorre porque o Turbopack não consegue executar plugins do webpack em paralelo para monitorizar alterações nos seus ficheiros de conteúdo. Para contornar isto, terá de usar o comando intlayer watch para executar simultaneamente o servidor de desenvolvimento e o watcher de build do Intlayer.

{  // ... As suas configurações existentes do package.json  "scripts": {    // ... As suas configurações de scripts existentes    "dev": "intlayer watch --with 'next dev'",  },}

Se você estiver usando next-intlayer@<=6.x.x, é necessário 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 essa limitação.

Configurar TypeScript

O Intlayer usa module augmentation para tirar proveito do TypeScript e tornar sua codebase 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", // Incluir os tipos gerados automaticamente  ],}

Configuração do Git

Recomenda-se ignorar os ficheiros gerados pelo Intlayer. Isto permite evitar comitar estes ficheiros no seu repositório Git.

Para isso, pode adicionar as seguintes instruções ao ficheiro .gitignore:

# Ignorar os ficheiros gerados pelo Intlayer.intlayer

Extensão do VS Code

Para melhorar a sua experiência de desenvolvimento com o Intlayer, pode instalar a extensão oficial Intlayer VS Code Extension.

Install from the VS Code Marketplace

Esta extensão fornece:

• Autocompletion para chaves de tradução.
• Detecção de erros em tempo real para traduções em falta.
• 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 mais longe

Para ir mais longe, você pode implementar o editor visual ou externalizar seu conteúdo usando o CMS.