Traduza uma aplicação Next.js com App Router

Disponibilize cada página com um prefixo de idioma, redirecione caminhos sem prefixo e renderize componentes de servidor e de cliente traduzidos com @lingo.dev/react-next.

No App Router, cada idioma tem seu próprio prefixo de URL, inclusive o idioma de origem: os leitores acessam /en/pricing e /de/pricing. @lingo.dev/react-next lê o idioma de um segmento de rota app/[locale], carrega o catálogo desse idioma no servidor e fornece as mesmas mensagens aos componentes de servidor e de cliente. Este guia adiciona alemão e francês a uma aplicação em inglês.

Use Next.js 16 ou posterior com React 19; os pontos de entrada leem o idioma por meio de next/root-params. Instale os pacotes:

sh
npm install @lingo.dev/react@1.22.0 @lingo.dev/react-next@1.22.0 @lingo.dev/locale-router@0.3.0
npm install --save-dev @lingo.dev/cli@latest

Defina os idiomas #

Crie i18n.ts na mesma pasta de app/ (src/i18n.ts se a aplicação usar src/):

ts
import { createLocaleRouter } from "@lingo.dev/locale-router";

export const locales = createLocaleRouter(["en", "de", "fr"] as const, { defaultLocale: "en", exclude: ["api"] });

export const localePath = (pathname: string, locale: string) =>
  locales.prefix(pathname, locales.toLocale(locale) ?? locales.defaultLocale);

Liste os idiomas em .lingo/config.json, com o idioma de origem como defaultLocale. exclude define os segmentos iniciais de caminho que não recebem prefixo, como os manipuladores de rota em app/api/. Não passe slugs: o segmento de URL de cada idioma deve ser sua tag em minúsculas (/pt-br para pt-BR), pois getLingo() determina o idioma apenas pelo segmento. Um slug personalizado faz o provedor lançar um erro que identifica esse slug. O proxy, os componentes de servidor e os componentes de cliente importam esse arquivo, então não adicione outras importações a ele.

Redirecione caminhos sem prefixo #

Crie proxy.ts na mesma pasta de app/:

ts
import { lingoProxy } from "@lingo.dev/react-next/app/proxy";
import { locales } from "./i18n";

export const proxy = lingoProxy(locales);

export const config = { matcher: ["/", "/((?!api|_next|.*\\..*).*)"] };

lingoProxy(locales) processa dois tipos de requisição:

RequisiçãoResposta
Um segmento inicial que identifica um idioma de outra forma que não pelo slug, como /DE/about, /de-AT ou /de_DE301 para o endereço canônico.
Um caminho localizado sem idioma, como /about307 para o idioma negociado a partir de Accept-Language, com Cache-Control: private, no-store e Vary: Accept-Language.
Qualquer outra requisiçãoundefined.

Os redirecionamentos preservam a string de consulta e o basePath da aplicação. O Next.js lê o padrão de correspondência durante a compilação, então mantenha-o como um valor literal e seu api em sincronia com exclude. Se a aplicação já tiver um proxy, chame lingoProxy primeiro e continue com sua própria lógica quando ele retornar undefined. Um middleware.ts é o mesmo arquivo com o nome antigo; renomeie-o para proxy.ts e sua função para proxy.

Mova as rotas para a pasta do idioma #

Mova o layout raiz e todas as páginas um nível abaixo na estrutura de pastas, para app/[locale]/. app/[locale]/layout.tsx passa a ser o layout raiz, e app/layout.tsx deixa de existir. Os manipuladores de rota em app/api/, globals.css, os ícones, robots.ts e sitemap.ts permanecem onde estão. Remova qualquer chave i18n de next.config; o App Router não a lê.

tsx
// app/[locale]/layout.tsx
import type { ReactNode } from "react";
import { getLingo, LingoAppProvider, lingoStaticParams } from "@lingo.dev/react-next/app/server";
import { locales } from "@/i18n";
import "../globals.css";

export function generateStaticParams() {
  return lingoStaticParams(locales);
}

export default async function RootLayout({ children }: { children: ReactNode }) {
  const l = await getLingo();
  return (
    <html lang={l.locale} dir={l.direction}>
      <body>
        <LingoAppProvider locales={locales}>{children}</LingoAppProvider>
      </body>
    </html>
  );
}

lingoStaticParams retorna um { locale } por idioma, de modo que a compilação pré-renderiza cada página uma vez por idioma. LingoAppProvider retorna um erro 404 para idiomas fora da lista. Não adicione export const dynamicParams = false: o Next.js o rejeita quando cacheComponents está ativado.

Traduza componentes de servidor e de cliente #

Componentes de servidor, páginas, layouts e generateMetadata chamam await getLingo() de @lingo.dev/react-next/app/server. Componentes de cliente chamam useLingo() de @lingo.dev/react; LingoAppProvider fornece a eles o idioma e o catálogo. Nenhum dos dois precisa receber o idioma por propriedades.

tsx
// app/[locale]/page.tsx
import { getLingo } from "@lingo.dev/react-next/app/server";

export default async function Home() {
  const l = await getLingo();
  return <h1>{l.text("Welcome", { context: "Heading of the start page" })}</h1>;
}

Um componente de servidor pode receber l como propriedade de seu componente pai no servidor, mas nunca passe l a um componente de cliente: funções não podem ser transferidas do servidor para o cliente. Chamar getLingo() fora de app/[locale]/ lança um erro porque nenhum segmento [locale] é encontrado.

Adicione metadados #

tsx
import { getLingo, lingoMetadata } from "@lingo.dev/react-next/app/server";
import { locales } from "@/i18n";

export async function generateMetadata() {
  const l = await getLingo();
  return {
    title: l.text("Pricing", { context: "Title of the pricing page" }),
    ...(await lingoMetadata({ locales, pathname: "/pricing", origin: "https://example.com" })),
  };
}

lingoMetadata({ locales, pathname, origin, ogLocale? }) retorna alternates.canonical, alternates.languages para cada idioma mais x-default, além de openGraph.url e openGraph.locale. Passe o caminho da página sem o prefixo de idioma, a string de consulta ou o fragmento; uma rota dinâmica monta esse caminho a partir de seus parâmetros. Substitua a origem do exemplo pela origem do seu site. Política de URLs por idioma explica lingoHead, que gera os valores, e a opção de substituição ogLocale.

Adicione o prefixo a cada link interno com localePath("/pricing", l.locale) de i18n.ts. l.locale é uma string simples, então localePath restringe seu tipo a um dos idiomas do roteador antes de locales.prefix adicionar o prefixo. Um link sem prefixo chega ao proxy, que redireciona para o idioma do navegador em vez do idioma da página. O mesmo se aplica a redirect(), router.push() e ações de formulário que especificam um caminho.

tsx
"use client";

import Link from "next/link";
import { useLocaleSwitch } from "@lingo.dev/react-next/app/client";
import { locales } from "@/i18n";

export function LocaleSwitcher() {
  const options = useLocaleSwitch(locales);
  return (
    <nav aria-label="Language">
      {options.map((option) => (
        <Link key={option.locale} href={option.href} hrefLang={option.locale} aria-current={option.current ? "page" : undefined}>
          {option.label}
        </Link>
      ))}
    </nav>
  );
}

useLocaleSwitch(locales) retorna um { locale, label, href, current } por idioma: a página atual nesse idioma, o nome do idioma no próprio idioma e a indicação de que ele é ou não o idioma atual. A string de consulta é adicionada após a hidratação, então uma página que renderiza o seletor de idiomas permanece estática. Ao seguir um link, o layout é renderizado novamente e carrega o catálogo do novo idioma.

Extraia e carregue os catálogos #

O servidor lê locales/<locale>.jsonc da pasta em que next é executado, usando fs, então mantenha i18n.messagesPath com o valor padrão locales. Ele descarta entradas órfãs e lê o arquivo novamente a cada requisição, de modo que next dev disponibiliza um catálogo editado já na requisição seguinte. Um arquivo ausente resulta em um catálogo vazio, com um aviso em desenvolvimento; um arquivo malformado ou um valor que não seja uma string gera um erro que identifica o arquivo. Em produção, o idioma de origem não envia catálogo ao navegador, pois seu texto é usado como alternativa.

Quando app/ estiver na raiz do projeto sem uma pasta src/, defina "i18n": { "src": "." } em .lingo/config.json para que a extração examine app/ e components/. A extração ignora node_modules e pastas cujo nome começa com ponto, como .next. Para uma nova configuração:

sh
npx lingo init --source en --targets de,fr --files 'locales/en.jsonc' --yes
npx lingo extract --src .
npx lingo login
npx lingo link
npx lingo push --backfill-missing --wait

Defina i18n.src após init, que reescreve a seção i18n. Em um monorepositório, .lingo/config.json fica na raiz do repositório e seus caminhos partem dali, então messagesPath é a pasta da aplicação seguida de locales, como apps/web/locales; consulte o mapa i18n de aplicações nomeadas em Configuração da CLI. O servidor continua lendo locales/ na pasta da própria aplicação.

Após next build e next start, abra / e verifique se há um redirecionamento para um idioma. Em seguida, abra /de e confira o texto em alemão no HTML.

Ambiente de execução #

Páginas pré-renderizadas funcionam em qualquer serviço de hospedagem. Uma página renderizada sob demanda lê seu catálogo do disco, então precisa do ambiente de execução Node.js; o Cloudflare Workers e o ambiente de execução Edge não conseguem ler esse catálogo.

Exportações #

Ponto de entradaExportações
@lingo.dev/react-next/app/servergetLingo(), LingoAppProvider, lingoMetadata(options), lingoStaticParams(locales).
@lingo.dev/react-next/app/clientuseLocaleSwitch(locales) e o tipo LocaleOption.
@lingo.dev/react-next/app/proxylingoProxy(locales).

Agentes de programação podem seguir lingo agent-guide react-next-app após a instalação do pacote e lingo agent-guide react-next-migrate para migrar do next-intl. Consulte Configure com um agente de programação.