Traduza uma aplicação Next.js Pages
Carregue as mensagens traduzidas de uma página, renderize-as com o wrapper do Pages e adicione um seletor de idioma e links alternativos.
Uma rota do Next.js Pages já determina o idioma de cada solicitação. @lingo.dev/react-next usa esse idioma para fornecer mensagens ao React, mantendo os dados da página e o texto traduzido juntos. Esta receita renderiza uma página Sobre em inglês e francês e preserva a seleção da rota mesmo quando o JSONC traduzido perde seus metadados.
Use uma aplicação Pages existente com React 19. O pacote declara Next.js 13+ e React 18/19 como dependências de mesmo nível, mas o provedor atual usa a sintaxe abreviada de contexto do React 19 em tempo de execução. Suas exportações são /pages, /pages/client e /pages/server; não há exportação na raiz nem ponto de entrada para o App Router.
Configure os idiomas e o wrapper da aplicação #
npm install @lingo.dev/react@1.17.1 @lingo.dev/react-next@1.17.1
npm install @lingo.dev/spec@1.17.1 jsonc-parser
npm install --save-dev @lingo.dev/cli@latestAdicione i18n ao seu next.config.mjs existente, mantendo as demais configurações:
export default {
i18n: { locales: ["en", "fr"], defaultLocale: "en" },
};Em pages/_app.tsx, envolva a aplicação com o wrapper:
import type { AppProps } from "next/app";
import { useRouter } from "next/router";
import { useEffect } from "react";
import { withLingoApp } from "@lingo.dev/react-next/pages/client";
function App({ Component, pageProps }: AppProps) {
const { locale, defaultLocale } = useRouter();
useEffect(() => {
document.documentElement.lang = locale ?? defaultLocale ?? "en";
}, [locale, defaultLocale]);
return <Component {...pageProps} />;
}
export default withLingoApp(App);O wrapper lê pageProps.__lingoMessages, determina o idioma ativo do Next e fornece LingoProvider. As próprias configurações de i18n do Next definem a política de URLs; normalmente, o caminho do idioma padrão, inglês, não recebe prefixo.
Escreva a página e carregue suas mensagens #
Primeiro, adicione como lib/catalog.ts a função loadMatchedMessages apresentada em Carregamento de catálogos. Ela valida o JSONC com valores do tipo string e associa os valores de destino às chaves de origem ativas.
Em seguida, crie pages/about.tsx:
import { readFile } from "node:fs/promises";
import path from "node:path";
import type { GetStaticProps } from "next";
import { useLingo, type Messages } from "@lingo.dev/react";
import { loadMatchedMessages } from "../lib/catalog";
export const getStaticProps: GetStaticProps<{ __lingoMessages: Messages }> = async (ctx) => {
const locale = ctx.locale ?? ctx.defaultLocale ?? "en";
if (!["en", "fr"].includes(locale)) return { notFound: true };
const source = await readFile(path.join(process.cwd(), "locales/en.jsonc"), "utf8");
const target =
locale === "en" ? source : await readFile(path.join(process.cwd(), "locales", `${locale}.jsonc`), "utf8");
const messages = loadMatchedMessages(source, target, (entry) => {
const route = entry.metadata.src?.replace(/\.\w+(?::\d+)?$/, "");
return !route || route === "pages/about" || (!route.startsWith("pages/") && !route.startsWith("src/pages/"));
});
return { props: { __lingoMessages: messages } };
};
export default function About() {
const l = useLingo();
return <h1>{l.text("About us", { context: "About page heading" })}</h1>;
}Este predicado mantém as entradas da própria página e as mensagens dos componentes compartilhados. Ele remove extensões e sufixos antigos de números de linha dos metadados de origem. Se a página estiver em src/pages/about.tsx, ajuste tanto o caminho de importação quanto a comparação de rota para esse local.
O carregador personalizado falha de propósito quando um arquivo obrigatório está ausente ou malformado, para impedir que a compilação substitua silenciosamente o catálogo esperado em francês pelo conteúdo de reserva em inglês. As chaves individuais ausentes no destino continuam ausentes e usam o mecanismo normal de conteúdo de reserva em tempo de execução.
Extraia, traduza e abra as duas rotas #
Execute npx lingo extract --src pages --source-locale en na raiz do projeto. Para criar uma configuração de projeto do Lingo.dev, execute:
npx lingo init --source en --targets fr --files 'locales/en.jsonc' --yes
npx lingo login
npx lingo link
npx lingo push --backfill-missing --waitSe o projeto já estiver configurado, preserve seu vínculo e as demais opções de arquivo. Após a extração, conclua as atualizações habituais dos idiomas de destino existentes, baixe os arquivos e confira seu conteúdo. Depois, adicione fr e preencha as traduções pendentes sem alterar essa revisão de origem. Carregamento de catálogos apresenta as etapas de configuração, e Adicionar um idioma explica a ordem necessária. Se os componentes compartilhados estiverem fora de pages, faça a extração a partir de um diretório que contenha todas as chamadas de mensagens ou organize-os em uma árvore src comum e use --src src.
Depois de baixar locales/fr.jsonc, execute o comando habitual de desenvolvimento ou compilação do Next. Abra /about e /fr/about. O primeiro usa o texto de origem em inglês; o segundo usa a tradução em francês para a mesma chave de título. Confira o texto em francês e o uso do texto de origem como reserva para uma entrada deixada ausente de propósito.
Carregamento integrado de propriedades estáticas #
Quando cada arquivo de idioma preserva os metadados corretos de @src e @orphan, a função auxiliar do servidor pode substituir o getStaticProps personalizado acima:
import { withLingoProps } from "@lingo.dev/react-next/pages/server";
export const getStaticProps = withLingoProps({ route: "pages/about" });withLingoProps({ route, handler? }) lê caminhos fixos de locales/<locale>.jsonc relativos ao diretório de trabalho. Ele filtra entradas órfãs e de outras páginas, tratando como compartilhadas as origens que não são páginas e as entradas sem @src. A tradução geral de JSONC mantém as marcações @orphan, mas remove os comentários @src. Por isso, para essa saída, use a receita de associação por chaves de origem apresentada acima; a função auxiliar não restaura os metadados.
Um arquivo ausente resulta em {}, com um aviso no ambiente de desenvolvimento; um arquivo existente, mas inválido, pode gerar uma exceção. Um manipulador assíncrono opcional adiciona propriedades ou retorna um resultado de redirecionamento ou de página não encontrada. Os resultados bem-sucedidos preservam campos como revalidate e adicionam __lingoMessages. Os tipos públicos dessa função usam contexto e resultados de propriedades estáticas; não presuma que qualquer manipulador de solicitações no servidor siga o mesmo contrato. As substituições do caminho do catálogo feitas pela CLI também não alteram esse diretório fixo do carregador.
Expanda os caminhos estáticos de rotas dinâmicas #
Para uma rota dinâmica, a função auxiliar do servidor expande cada entrada de parâmetros para todos os idiomas configurados no Next:
import { withLingoPaths } from "@lingo.dev/react-next/pages/server";
export const getStaticPaths = withLingoPaths(async () => [{ params: { slug: "refund-policy" } }], {
fallback: "blocking",
});O valor padrão de fallback é "blocking"; false e true também são aceitos. A expansão não traduz slugs nem garante que todos os catálogos contenham as mensagens da rota.
Troque o idioma e adicione links alternativos #
Renderize um seletor abaixo do wrapper da aplicação:
import { LingoHead, useLocaleSwitch } from "@lingo.dev/react-next/pages/client";
export function Languages() {
const switchLocale = useLocaleSwitch();
return (
<nav aria-label="Language">
<LingoHead baseUrl="https://example.com" />
<button onClick={() => switchLocale("en")}>English</button>
<button onClick={() => switchLocale("fr")}>Français</button>
</nav>
);
}Substitua a origem do exemplo pela origem absoluta do site em produção. LingoHead gera links alternativos para os idiomas configurados e x-default, omitindo o prefixo do idioma padrão. Ele não gera metadados canônicos nem Open Graph. Confira se as URLs resultantes seguem sua política de rotas e parâmetros de consulta.
A função de retorno da troca de idioma grava NEXT_LOCALE com validade de um ano em /, com SameSite=Lax, e depois navega pelo roteador do Next usando o asPath atual. Forneça os idiomas configurados, como no exemplo acima; a função não verifica se entradas arbitrárias constam na lista de idiomas compatíveis.
Defina os atributos iniciais do documento #
Defina os atributos iniciais em pages/_document.tsx, preservando as personalizações existentes do documento:
import Document, { Html, Head, Main, NextScript } from "next/document";
import { createLingo } from "@lingo.dev/react";
export default class LocalizedDocument extends Document {
render() {
const locale = this.props.__NEXT_DATA__.locale ?? "en";
return (
<Html lang={locale} dir={createLingo(locale).direction}>
<Head />
<body>
<Main />
<NextScript />
</body>
</Html>
);
}
}withLingoApp define a direção após as mudanças de idioma e gera um script RTL embutido para a renderização inicial, mas não define lang. O efeito _app acima atualiza lang durante a navegação; o documento personalizado fornece os dois atributos iniciais. Uma política de segurança de conteúdo rigorosa pode bloquear o script embutido do wrapper, que não oferece uma opção de nonce. O documento personalizado fornece a direção inicial sem depender desse script. Verifique também a política de scripts da aplicação durante a navegação.
Por fim, verifique a hidratação com o mesmo catálogo e valores de tempo explícitos. Confirme que a troca de idioma altera as mensagens e os atributos do documento em conjunto.