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

Disponibilize todas as páginas 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 o seu próprio prefixo de URL, incluindo o idioma de origem: os leitores acedem a /en/pricing e /de/pricing. @lingo.dev/react-next lê o idioma a partir 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 mostra como adicionar alemão e francês a uma aplicação em inglês.

Utilize o Next.js 16 ou posterior com o React 19; os pontos de entrada leem o idioma através 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

Definir os idiomas #

Crie i18n.ts na mesma pasta que app/ (src/i18n.ts se a aplicação utilizar 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 definido como defaultLocale. exclude indica os primeiros segmentos de caminho que não recebem prefixo, como os dos processadores de rotas em app/api/. Não passe slugs: o segmento de URL de cada idioma tem de ser a respetiva etiqueta em minúsculas (/pt-br para pt-BR), porque getLingo() determina o idioma apenas a partir do segmento. Um identificador de URL personalizado faz com que o fornecedor lance um erro que identifica esse valor. O proxy e os componentes de servidor e de cliente importam este ficheiro, por isso não inclua outras importações.

Redirecionar caminhos sem prefixo #

Crie proxy.ts na mesma pasta que 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 pedidos:

PedidoResposta
Um primeiro segmento que identifica um idioma por um valor diferente do respetivo identificador de URL, 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 outro casoundefined.

Os redirecionamentos preservam a cadeia de consulta e o basePath da aplicação. O Next.js lê o padrão de correspondência durante a compilação, por isso mantenha-o como um valor literal e o respetivo api em sintonia com exclude. Se a aplicação já tiver um proxy, chame primeiro lingoProxy e prossiga com a sua própria lógica quando essa chamada devolver undefined. middleware.ts é o mesmo ficheiro com o nome antigo; mude o nome do ficheiro para proxy.ts e o da função para proxy.

Mover as rotas para o segmento de idioma #

Mova a disposição de raiz e todas as páginas um nível abaixo na estrutura de pastas, para app/[locale]/. app/[locale]/layout.tsx passa a ser a disposição de raiz e deixa de existir app/layout.tsx. Os processadores de rotas em app/api/, globals.css, os ícones, robots.ts e sitemap.ts mantêm-se 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 devolve um { locale } por idioma, pelo que a compilação pré-renderiza cada página uma vez por idioma. LingoAppProvider devolve um erro 404 para idiomas que não constem da lista. Não adicione export const dynamicParams = false: o Next.js rejeita-o quando cacheComponents está ativado.

Traduzir componentes de servidor e de cliente #

Os componentes de servidor, as páginas, as disposições e generateMetadata chamam await getLingo() de @lingo.dev/react-next/app/server. Os componentes de cliente chamam useLingo() de @lingo.dev/react; LingoAppProvider fornece-lhes o idioma e o catálogo. Em nenhum dos casos é necessário passar o idioma a partir dos componentes superiores.

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 do componente de servidor pai, mas nunca passe l a um componente de cliente: as funções não podem passar do servidor para o cliente. Uma chamada a getLingo() fora de app/[locale]/ lança um erro por não encontrar nenhum segmento [locale].

Adicionar 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? }) devolve alternates.canonical, alternates.languages para cada idioma e ainda x-default, bem como openGraph.url e openGraph.locale. Passe o caminho da página sem o prefixo de idioma, a consulta ou o fragmento; uma rota dinâmica constrói esse caminho a partir dos respetivos parâmetros. Substitua a origem do exemplo pela origem do seu site. A política de URL por idioma explica lingoHead, que constrói os valores, e a opção de substituição ogLocale.

Adicione o respetivo prefixo a cada ligação interna com localePath("/pricing", l.locale) de i18n.ts. l.locale é uma simples cadeia de texto, por isso localePath restringe-a a um dos idiomas do encaminhador antes de locales.prefix adicionar o prefixo. Uma ligação 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 às ações de formulário que indicam 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) devolve um { locale, label, href, current } por idioma: a página atual nesse idioma, o nome do idioma na própria língua e a indicação de que é ou não o idioma atual. A cadeia de consulta é adicionada após a hidratação, pelo que uma página que renderiza o seletor se mantém estática. Seguir uma ligação volta a renderizar a disposição, que carrega o catálogo do novo idioma.

Extrair e carregar os catálogos #

O servidor lê locales/<locale>.jsonc a partir da pasta onde next é executado, utilizando fs, por isso mantenha i18n.messagesPath no valor predefinido locales. Descarta as entradas órfãs e volta a ler o ficheiro a cada pedido, pelo que next dev disponibiliza a versão editada do catálogo no pedido seguinte. Se o ficheiro não existir, o resultado é um catálogo vazio, com um aviso em desenvolvimento; um ficheiro malformado ou um valor que não seja uma cadeia de texto dá origem a um erro que identifica o ficheiro. Em produção, não é enviado nenhum catálogo do idioma de origem para o navegador, porque o respetivo texto serve de alternativa.

Quando app/ está na raiz do projeto e não existe uma pasta src/, defina "i18n": { "src": "." } em .lingo/config.json para que a extração analise app/ e components/. A extração ignora node_modules e as pastas cujo nome começa por um 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 depois de init, que reescreve a secção i18n. Num monorepositório, .lingo/config.json fica na raiz do repositório e os respetivos caminhos são relativos a essa raiz, pelo que messagesPath corresponde à pasta da aplicação seguida de locales, como apps/web/locales; consulte o mapa i18n de aplicações identificadas por nome em Configuração da CLI. O servidor continua a ler locales/ na pasta da própria aplicação.

Depois de next build e next start, abra / e confirme que redireciona para um idioma. Em seguida, abra /de e confirme que o texto em alemão aparece no HTML.

Ambiente de execução #

As páginas pré-renderizadas funcionam em qualquer serviço de alojamento. Uma página renderizada a pedido lê o respetivo catálogo do disco, pelo que precisa do ambiente de execução Node.js; o Cloudflare Workers e o ambiente de execução Edge não o conseguem ler.

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).

Depois de instalar o pacote, os agentes de programação podem seguir lingo agent-guide react-next-app e, para migrar do next-intl, lingo agent-guide react-next-migrate. Consulte Configurar com um agente de programação.