Traduzir uma aplicação Next.js Pages

Carregue as mensagens traduzidas de uma página, apresente-as através do componente envolvente do Pages e adicione um seletor de idioma e ligações alternativas.

Uma rota do Next.js Pages já determina o idioma do respetivo pedido. @lingo.dev/react-next utiliza esse idioma para fornecer mensagens ao React, mantendo os dados da página e o texto traduzido juntos. Este guia apresenta uma página Sobre em inglês e francês e preserva a seleção da rota quando o JSONC traduzido perde os metadados.

Utilize uma aplicação Pages existente com React 19. O pacote declara Next.js 13+ e React 18/19 como dependências pares, mas o componente que fornece o contexto em tempo de execução utiliza atualmente a sintaxe abreviada de contexto do React 19. As suas exportações são /pages, /pages/client e /pages/server; não tem uma exportação na raiz nem um ponto de entrada para o App Router.

Configurar os idiomas e o componente envolvente da aplicação #

sh
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@latest

Adicione i18n ao seu next.config.mjs existente, mantendo as restantes definições:

js
export default {
  i18n: { locales: ["en", "fr"], defaultLocale: "en" },
};

Em pages/_app.tsx, envolva a aplicação:

tsx
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 componente envolvente lê pageProps.__lingoMessages, determina o idioma ativo do Next e fornece LingoProvider. As definições de i18n do próprio Next determinam a política de URLs; o caminho do idioma predefinido, o inglês, normalmente não tem prefixo.

Escrever a página e carregar as suas mensagens #

Primeiro, adicione a função loadMatchedMessages apresentada em carregamento de catálogos como lib/catalog.ts. Esta valida o JSONC cujos valores são cadeias de texto e associa os valores de destino às chaves de origem ativas.

Em seguida, crie pages/about.tsx:

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 partilhados. Remove dos metadados de origem as extensões e os sufixos antigos com números de linha. Se a página estiver em src/pages/about.tsx, ajuste tanto o caminho de importação como a comparação da rota em conformidade.

O carregador personalizado falha deliberadamente quando um ficheiro obrigatório está em falta ou malformado, impedindo que uma compilação substitua silenciosamente o catálogo esperado em francês pelo inglês como alternativa. As chaves de destino individuais em falta continuam ausentes e recorrem ao mecanismo habitual de alternativa em tempo de execução.

Extrair, traduzir e abrir ambas as rotas #

Execute npx lingo extract --src pages --source-locale en a partir da raiz do projeto. Para configurar um novo projeto Lingo.dev, execute:

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

Num projeto já configurado, mantenha a associação existente e as restantes opções dos ficheiros. Após a extração, conclua as atualizações habituais dos idiomas de destino existentes, obtenha-as e verifique-as. Em seguida, adicione fr e preencha as entradas em falta sem alterar essa revisão da origem. Carregamento de catálogos apresenta os passos de configuração e Adicionar um idioma explica a ordem a seguir. Se os componentes partilhados 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 numa árvore src comum e utilize --src src.

Depois de obter locales/fr.jsonc, execute o comando habitual de desenvolvimento ou compilação do Next. Abra /about e /fr/about. A primeira rota utiliza o texto de origem em inglês; a segunda utiliza a tradução em francês para a mesma chave de título. Verifique o texto apresentado em francês e confirme que uma entrada deliberadamente em falta recorre ao texto de origem.

Carregamento integrado de propriedades estáticas #

Quando cada ficheiro de idioma mantém os metadados @src e @orphan corretos, a função auxiliar do servidor pode substituir o getStaticProps personalizado acima:

ts
import { withLingoProps } from "@lingo.dev/react-next/pages/server";

export const getStaticProps = withLingoProps({ route: "pages/about" });

withLingoProps({ route, handler? }) lê caminhos locales/<locale>.jsonc fixos, relativos ao diretório de trabalho. Exclui as entradas órfãs e as de outras páginas, tratando como partilhadas as origens que não são páginas e as entradas sem @src. A tradução geral de JSONC mantém as marcas @orphan, mas remove os comentários @src. Por isso, para esse resultado, utilize o procedimento de associação por chaves de origem descrito acima; a função auxiliar não restaura os metadados.

Se faltar um ficheiro, é devolvido {} com um aviso em ambiente de desenvolvimento; um ficheiro existente mas inválido pode gerar uma exceção. Um processador assíncrono opcional adiciona propriedades ou devolve um resultado de redirecionamento ou de página não encontrada. Os resultados bem-sucedidos mantêm campos como revalidate e adicionam __lingoMessages. Os seus tipos públicos utilizam o contexto e os resultados de propriedades estáticas; não pressuponha que qualquer processador de pedidos do lado do servidor segue o mesmo contrato. As opções da CLI que substituem os caminhos dos catálogos também não alteram este diretório fixo do carregador.

Expandir caminhos estáticos dinâmicos #

Para uma rota dinâmica, a função auxiliar do servidor expande cada entrada de parâmetros para todos os idiomas configurados no Next:

ts
import { withLingoPaths } from "@lingo.dev/react-next/pages/server";

export const getStaticPaths = withLingoPaths(async () => [{ params: { slug: "refund-policy" } }], {
  fallback: "blocking",
});

O valor predefinido para o mecanismo de alternativa é "blocking"; false e true também são suportados. A expansão não traduz os identificadores de URL nem garante que todos os catálogos contêm as mensagens da rota.

Mudar de idioma e adicionar ligações alternativas #

Apresente um seletor de idioma dentro do componente envolvente da aplicação:

tsx
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 ligações alternativas para os idiomas configurados e x-default, omitindo o prefixo do idioma predefinido. Não gera metadados canónicos nem Open Graph. Verifique os URLs resultantes tendo em conta a política de rotas e parâmetros de consulta do site.

A função de retorno de chamada para a mudança de idioma grava NEXT_LOCALE com validade de um ano em / com SameSite=Lax e, em seguida, navega com o encaminhador do Next utilizando o asPath atual. Forneça os idiomas configurados, como no exemplo acima; a função não verifica se os valores recebidos constam da lista de idiomas suportados.

Definir os atributos iniciais do documento #

Defina os atributos iniciais em pages/_document.tsx, mantendo as personalizações existentes do documento:

tsx
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 cada mudança de idioma e gera um script RTL incorporado para a apresentação inicial, mas não define lang. O efeito _app acima atualiza lang durante a navegação; o documento personalizado fornece ambos os atributos iniciais. Uma política de segurança de conteúdo rigorosa pode bloquear o script incorporado do componente envolvente, que não disponibiliza 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 temporais explícitos. Confirme que a mudança de idioma altera as mensagens e os atributos do documento em simultâneo.