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:
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@latestDefinir os idiomas #
Crie i18n.ts na mesma pasta que app/ (src/i18n.ts se a aplicação utilizar src/):
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/:
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:
| Pedido | Resposta |
|---|---|
Um primeiro segmento que identifica um idioma por um valor diferente do respetivo identificador de URL, como /DE/about, /de-AT ou /de_DE | 301 para o endereço canónico. |
Um caminho localizado sem idioma, como /about | 307 para o idioma negociado a partir de Accept-Language, com Cache-Control: private, no-store e Vary: Accept-Language. |
| Qualquer outro caso | undefined. |
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ê.
// 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.
// 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 #
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.
Criar ligações e mudar de idioma #
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.
"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:
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 --waitDefina 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 entrada | Exportações |
|---|---|
@lingo.dev/react-next/app/server | getLingo(), LingoAppProvider, lingoMetadata(options), lingoStaticParams(locales). |
@lingo.dev/react-next/app/client | useLocaleSwitch(locales) e o tipo LocaleOption. |
@lingo.dev/react-next/app/proxy | lingoProxy(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.