Localize Markdoc com Next.js

Roteie, carregue, traduza e renderize documentos Markdoc específicos de cada idioma junto com catálogos de interface separados em uma aplicação Next.js com App Router.

Um artigo traduzido precisa estar em sintonia com o restante da página. Em um site Next.js, o idioma da rota pode determinar tanto o documento Markdoc quanto um catálogo de interface separado para a navegação. Este guia conecta esses arquivos a uma página do App Router e depois os traduz pela CLI.

Use um projeto Next.js existente com App Router e Markdoc. O exemplo lê arquivos locais no servidor e não depende de um adaptador de localização para React.

Escolha uma estrutura de arquivos por idioma #

Um projeto de exemplo pode manter documentos e catálogos de interface juntos, organizados por idioma:

text
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 como identificadores de conteúdo. Traduzir um título não exige renomear home.mdoc. Se optar por localizar os slugs, mantenha um mapeamento explícito para a navegação e os links para outros idiomas; traduzir o corpo do texto não cria esse mapeamento.

Restrinja o idioma da rota e o slug do documento a conjuntos conhecidos antes de montar um caminho no sistema de arquivos. Defina uma política para traduções ausentes: retornar uma resposta de não encontrado ou recorrer explicitamente ao idioma de origem. O exemplo de página inicial abaixo usa um nome de documento fixo e retorna uma resposta de não encontrado para idiomas não compatíveis ou arquivos ausentes.

Selecione o processador de Markdoc e os metadados visíveis #

Instale e vincule a CLI a partir da raiz do projeto:

sh
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets es --files 'src/content/en/pages/*.mdoc' --yes
lingo link

Mantenha os IDs gerados da organização e do engine de localização em .lingo/config.json e configure a seleção completa dos arquivos de origem:

json
{
  "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; declarar o formato explicitamente deixa a intenção clara. Se um projeto existente armazena sintaxe Markdoc em .md, defina format: "markdoc" explicitamente. Caso contrário, a detecção pela extensão seleciona Markdown comum. Essa diferença é importante para tags personalizadas e atributos de componentes selecionados.

Escolha com cuidado os campos visíveis do frontmatter. Mantenha datas, autores, IDs estáveis e metadados de roteamento inalterados, a menos que sua política de conteúdo exija uma transformação específica. Declare propriedades de componentes como traduzíveis apenas quando contiverem texto destinado ao leitor. Consulte Markdoc para conhecer o comportamento do processador e Configuração da CLI para ver os nomes das opções de arquivo; as opções da API de documentos usam um esquema diferente.

Use um catálogo de interface por idioma. Para outras estruturas de geradores de sites, consulte Conteúdo estático.

Renderize a página inicial de origem pela rota do idioma #

Adicione a src/content/en/pages/home.mdoc um título e uma descrição no frontmatter YAML, seguidos pelo 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.

Este exemplo mínimo de src/app/[lang]/page.tsx lê as páginas iniciais de origem e de destino pelo mesmo fluxo de carregamento. Ele usa os parâmetros de rota baseados em promessas da versão atual do App Router:

tsx
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 /en primeiro. Este exemplo usa nós padrão do Markdoc. Para um site com tags personalizadas, passe a configuração real do site tanto para Markdoc.validate quanto para Markdoc.transform e forneça os componentes React nomeados a Markdoc.renderers.react. Passe as variáveis necessárias explicitamente. O processador de tradução preserva as anotações; ele não fornece o esquema de tags do site.

Estenda o mesmo carregador validado à geração de metadados e a outras rotas. Para slugs dinâmicos de documentos, resolva uma entrada conhecida do inventário antes de ler um caminho. Um carregador que usa o sistema de arquivos do Node exige que os arquivos de conteúdo estejam incluídos no artefato de implantação; verifique essa inclusão na compilação de produção. Uma implantação em Edge sem acesso ao sistema de arquivos exige outra forma de ler os dados armazenados.

Alinhe a negociação de idioma à navegação #

Para rotas sem idioma, use a preferência explícita da aplicação ou negocie um idioma compatível a partir de Accept-Language. Analise os pesos de qualidade e as tags regionais e redirecione para a rota [lang] correspondente, preservando o restante do caminho.

Não redirecione rotas que já contenham um idioma compatível, requisições de API, recursos internos do Next.js ou arquivos estáticos. Um padrão de correspondência amplo pode criar ciclos ou redirecionar requisições de imagens para rotas de documentos. Aplique as exclusões aceitas pela API de interceptação de rotas da versão instalada do Next.js. Projetos mais antigos usam middleware; versões mais recentes podem usar a convenção renomeada para proxy. Mantenha o comportamento e os testes alinhados à versão instalada, em vez de tratar um nome de arquivo antigo como receita universal.

Crie links internos e para outros idiomas a partir de mapeamentos de rotas conhecidos. Confirme que cada destino existe antes de oferecê-lo em um seletor de idioma. Verifique também os fragmentos de títulos, pois títulos traduzidos podem gerar IDs diferentes.

Gere apenas rotas cujos documentos estejam disponíveis #

Para geração estática, enumere os pares de idioma e slug compatíveis a partir do inventário real de conteúdo. Inclua-os no fluxo de generateStaticParams do projeto e inspecione as rotas geradas. Para carregamento dinâmico, faça a mesma verificação do inventário no momento da requisição e trate explicitamente os arquivos ausentes. Não gere todas as rotas de destino a partir da lista de idiomas presumindo que suas traduções existem.

Traduza os arquivos de destino ausentes com lingo push --backfill-missing --wait. Após a conclusão, confirme que src/content/es/pages/home.mdoc e src/content/es/ui.json existem e abra /es pelo mesmo carregador. Inspecione o título, a descrição, o corpo, os links, os blocos de código e a estrutura de tags personalizadas na tradução. Os exemplos de código e os atributos de comportamento devem manter o significado e os valores de origem.

Quando as correções locais nos arquivos de destino precisarem de proteção contra divergências, envie sem --wait e inspecione lingo pull --dry-run antes de recuperar o resultado; a gravação direta após a espera não oferece essa etapa de controle. Siga Preservar traduções revisadas.

Verifique uma página antes de tornar a tradução recorrente #

Abra diretamente uma rota do idioma de destino e depois navegue até ela pelo site. Confirme que o título, os elementos da interface, os metadados e o seletor de idioma usam o idioma esperado. Verifique um componente personalizado e um exemplo de código e siga um link interno e um fragmento de título. Execute a compilação Next.js já usada pelo projeto e a validação do Markdoc com os arquivos traduzidos.

Mantenha juntos os arquivos de origem, as traduções de destino aceitas, a configuração e o Lockfile da CLI. As alterações posteriores na origem seguem o workflow normal de lingo push --wait. Quando a página estiver funcionando, escolha a tradução gerenciada no GitHub ou uma receita de executor com gravação dos resultados sujeita a revisão. Mantenha a validação do carregador de conteúdo e a compilação do Next.js nesse ciclo; lingo check não garante que os documentos estejam completos nem que as tags personalizadas sejam renderizadas corretamente.