Localizar Markdoc com Next.js
Encaminhe, carregue, traduza e apresente documentos Markdoc específicos de cada idioma, com catálogos de interface separados, numa aplicação Next.js com App Router.
Um artigo traduzido tem de estar em sintonia com a página onde se insere. Num site Next.js, o idioma da rota pode determinar tanto o documento Markdoc como um catálogo de interface separado para a navegação. Este guia mostra como ligar esses ficheiros a uma página do App Router e depois traduzi-los através da CLI.
Utilize um projeto Next.js existente com App Router e Markdoc. O exemplo lê ficheiros locais no servidor e não depende de um adaptador de localização para React.
Escolher uma estrutura de ficheiros por idioma #
Um projeto de exemplo pode organizar os documentos e os catálogos de interface por idioma:
src/content/
en/
pages/home.mdoc
blog/welcome.mdoc
ui.json
es/
pages/home.mdoc
blog/welcome.mdoc
ui.json
src/app/[lang]/Mantenha os slugs estáveis quando servirem de identificadores de conteúdo. Traduzir um título não implica mudar o nome de home.mdoc. Se optar por localizar os slugs, mantenha um mapeamento explícito para a navegação e as ligações para outros idiomas; a tradução do corpo do documento não cria esse mapeamento.
Antes de construir um caminho no sistema de ficheiros, confirme que o idioma da rota e o slug do documento pertencem a conjuntos conhecidos. Defina como tratar as traduções em falta: devolver uma resposta de conteúdo não encontrado ou recorrer explicitamente ao idioma de origem. O exemplo de página inicial abaixo utiliza um nome de documento fixo e devolve uma resposta de conteúdo não encontrado para idiomas não suportados ou ficheiros em falta.
Selecionar o processador de Markdoc e os metadados visíveis #
Instale e associe a CLI a partir da raiz do projeto:
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets es --files 'src/content/en/pages/*.mdoc' --yes
lingo linkMantenha em .lingo/config.json os IDs gerados para a organização e o motor de localização e, em seguida, configure a seleção completa dos ficheiros de origem:
{
"orgId": "org_...",
"engineId": "eng_...",
"sourceLocale": "en",
"targetLocales": ["es"],
"files": [
{
"pattern": "src/content/en/pages/*.mdoc",
"format": "markdoc",
"translateFrontmatterFields": ["title", "description"]
},
{
"pattern": "src/content/en/blog/*.mdoc",
"format": "markdoc",
"translateFrontmatterFields": ["title", "description"]
},
{ "pattern": "src/content/en/ui.json" }
]
}.mdoc seleciona Markdoc automaticamente; indicar o formato de forma explícita torna a intenção clara. Se um projeto existente guardar sintaxe Markdoc em .md, defina format: "markdoc" explicitamente. Caso contrário, a deteção pela extensão seleciona Markdown comum. Esta diferença é importante para as etiquetas personalizadas e os atributos de componentes selecionados.
Selecione criteriosamente os campos visíveis dos metadados iniciais. Mantenha as datas, os autores, os IDs estáveis e os metadados de encaminhamento inalterados, a menos que a sua política de conteúdo exija uma transformação específica. Declare as propriedades dos componentes como traduzíveis apenas quando contiverem texto destinado a quem lê. Consulte Markdoc para conhecer o comportamento do processador e Configuração da CLI para consultar os nomes das opções de ficheiro; as opções da API de documentos utilizam um esquema diferente.
Utilize um catálogo de interface por idioma. Para outras estruturas de geradores de sites, consulte Conteúdo estático.
Apresentar a página inicial de origem através da rota do respetivo idioma #
Adicione a src/content/en/pages/home.mdoc um título e uma descrição nos metadados iniciais em YAML, seguidos do corpo do artigo. Em src/content/en/ui.json, adicione {"home": "Home"} para o rótulo de navegação. Instale @markdoc/markdoc e yaml se ainda não forem dependências do projeto.
Esta versão mínima de src/app/[lang]/page.tsx lê a página inicial de origem e a de destino através do mesmo processo de carregamento. Utiliza os parâmetros de rota baseados em promessas da versão atual do App Router:
import { readFile } from "node:fs/promises";
import path from "node:path";
import React from "react";
import Markdoc from "@markdoc/markdoc";
import { parse as parseYaml } from "yaml";
import { notFound } from "next/navigation";
export const runtime = "nodejs";
export default async function Page({
params,
}: {
params: Promise<{ lang: string }>;
}) {
const { lang } = await params;
if (lang !== "en" && lang !== "es") notFound();
const root = path.join(process.cwd(), "src/content", lang);
let rawDocument: string;
let rawUi: string;
try {
[rawDocument, rawUi] = await Promise.all([
readFile(path.join(root, "pages/home.mdoc"), "utf8"),
readFile(path.join(root, "ui.json"), "utf8"),
]);
} catch (error) {
if ((error as NodeJS.ErrnoException).code === "ENOENT") notFound();
throw error;
}
const ast = Markdoc.parse(rawDocument);
const errors = Markdoc.validate(ast);
if (errors.some(({ error }) => ["error", "critical"].includes(error.level))) {
throw new Error("Invalid Markdoc document");
}
const metadata = parseYaml(ast.attributes.frontmatter ?? "");
const ui = JSON.parse(rawUi);
if (typeof metadata?.title !== "string" || typeof ui.home !== "string") {
throw new Error("Missing homepage title or navigation label");
}
const tree = Markdoc.transform(ast);
return (
<main lang={lang}>
<nav><a href={`/${lang}`}>{ui.home}</a></nav>
<h1>{metadata.title}</h1>
{Markdoc.renderers.react(tree, React)}
</main>
);
}Abra primeiro /en. Este exemplo utiliza nós Markdoc padrão. Num site com etiquetas personalizadas, passe a configuração efetiva do site tanto a Markdoc.validate como a Markdoc.transform e, em seguida, forneça a Markdoc.renderers.react os componentes React identificados por nome. Passe explicitamente as variáveis necessárias. O processador de tradução preserva as anotações; não fornece o esquema de etiquetas do site.
Alargue a utilização do mesmo carregador validado à geração de metadados e a outras rotas. Para slugs de documentos dinâmicos, identifique uma entrada conhecida do inventário antes de ler um caminho. Um carregador baseado no sistema de ficheiros do Node exige que os ficheiros de conteúdo estejam incluídos no artefacto de implementação; confirme a sua inclusão na compilação de produção. Uma implementação Edge sem acesso ao sistema de ficheiros precisa de um leitor de armazenamento diferente.
Alinhar a negociação de idioma com a navegação #
Para rotas sem idioma, utilize a preferência explícita da aplicação ou negoceie um idioma suportado a partir de Accept-Language. Analise os pesos de qualidade e as etiquetas regionais e, em seguida, redirecione para a rota [lang] correspondente, preservando o resto do caminho.
Não redirecione rotas que já incluam um idioma suportado, pedidos à API, recursos internos do Next.js ou ficheiros estáticos. Uma regra de correspondência demasiado abrangente pode criar ciclos ou redirecionar pedidos de imagens para rotas de documentos. Aplique as exclusões suportadas pela API de interceção de rotas da versão do Next.js instalada. Os projetos mais antigos utilizam middleware; as versões mais recentes podem utilizar a convenção entretanto renomeada para proxy. Mantenha o comportamento e os testes alinhados com a versão instalada, em vez de adotar um nome de ficheiro antigo como solução universal.
Crie ligações internas e para outros idiomas a partir de mapeamentos de rotas conhecidos. Confirme que cada destino existe antes de o disponibilizar num seletor de idioma. Verifique também os fragmentos de ligação a títulos, pois os títulos traduzidos podem gerar IDs diferentes.
Gerar apenas rotas com documentos disponíveis #
Para a geração estática, enumere os pares de idioma e slug suportados a partir do inventário real de conteúdo. Inclua-os no processo de generateStaticParams do projeto e inspecione as rotas geradas. Para o carregamento dinâmico, aplique a mesma verificação do inventário no momento do pedido e defina como tratar os ficheiros em falta. Não gere todas as rotas de destino a partir da lista de idiomas, partindo do princípio de que as respetivas traduções existem.
Traduza os ficheiros de destino em falta com lingo push --backfill-missing --wait. Quando a tradução terminar, confirme que src/content/es/pages/home.mdoc e src/content/es/ui.json existem e, em seguida, abra /es através do mesmo carregador. Inspecione o título, a descrição, o corpo e as ligações traduzidos, os delimitadores dos blocos de código e a estrutura das etiquetas personalizadas. Os exemplos de código e os atributos que controlam o comportamento devem manter o significado e os valores de origem.
Quando precisar de proteger as correções locais nos ficheiros de destino contra divergências, submeta sem --wait e inspecione lingo pull --dry-run antes de obter os resultados; a gravação direta após a espera não inclui esse ponto de controlo. Siga Preservar traduções revistas.
Verificar uma página antes de tornar a tradução recorrente #
Abra diretamente uma rota do idioma de destino e, em seguida, aceda-lhe através da navegação do site. Confirme que o título, os elementos da interface, os metadados e o seletor de idioma utilizam o idioma pretendido. Verifique um componente personalizado e um exemplo de código e siga uma ligação interna e uma ligação para um fragmento de título. Execute a compilação Next.js já definida no projeto e a validação Markdoc sobre os ficheiros traduzidos.
Mantenha juntos os ficheiros de origem, os ficheiros de destino aceites, a configuração e o Lockfile da CLI. As alterações posteriores à origem seguem o workflow habitual de lingo push --wait. Quando a página estiver a funcionar, escolha a tradução gerida no GitHub ou uma receita de execução com gravação de resultados que permita revisão. Mantenha a validação do carregador de conteúdo e a compilação Next.js nesse ciclo; lingo check não garante que os documentos estejam completos nem que as etiquetas personalizadas sejam apresentadas corretamente.