Localização do App Router do Next.js com Markdoc

A CLI da Lingo.dev traduz arquivos Markdoc e catálogos JSON de strings de UI por meio de um engine de localização configurado. O Markdoc é um formato de autoria baseado em Markdown com tags personalizadas tipadas e integradas ao React — ideal para sites em Next.js App Router que combinam conteúdo extenso com componentes interativos.

Este guia mostra, de ponta a ponta, como localizar um site em Next.js App Router: configurar a CLI, organizar o conteúdo por idioma, renderizar Markdoc em rotas dinâmicas e automatizar as traduções com GitHub Actions.

Como funciona a localização com Next.js + Markdoc#

A maioria dos sites em Next.js App Router divide o conteúdo localizado em duas camadas:

As rotas ficam em src/app/[lang]/ e leem, no momento da requisição, os arquivos do idioma correspondente. Um middleware define um idioma padrão com base no cabeçalho Accept-Language do navegador e redireciona caminhos sem prefixo, como /, para /en (ou para a melhor correspondência disponível).

O bucket markdoc da CLI processa arquivos Markdoc preservando o frontmatter e as tags personalizadas, enquanto o bucket json cuida do catálogo de strings de UI. Ambos traduzem apenas o delta por meio do seu engine de localização e gravam arquivos por idioma ao lado da origem.

Pré-requisitos#

node -v

Organize o conteúdo#

Separe o conteúdo por função. Páginas e posts longos são escritos em Markdoc; strings curtas de UI ficam em JSON para que os componentes possam carregá-las diretamente.

src/content/
  en/                  # Source locale
    pages/home.md      # Long-form Markdoc
    blog/hello.md
    ui.json            # UI strings (navbar, CTAs, button states)
  es/                  # Target locales – generated by Lingo.dev
  fr/
  de/

Arquivos Markdoc aceitam frontmatter para metadados por página (título, descrição, data, autor) e tags personalizadas renderizadas como componentes React. Uma página mínima se parece com isto:

---
title: Author once in Markdoc, ship in every language.
description: An example Next.js App Router app that localizes Markdoc with Lingo.
---

{% inline-callout type="info" %}
This page is authored in Markdoc and translated by Lingo.dev.
{% /inline-callout %}

## Built from three pieces

Markdoc custom tags render as React components – even interactive ones.

Configure a CLI#

Crie um arquivo i18n.json na raiz do projeto. Declare dois buckets — um para o conteúdo em Markdoc e outro para o catálogo de strings de UI:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.15",
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de"]
  },
  "buckets": {
    "markdoc": {
      "include": [
        "src/content/[locale]/pages/*.md",
        "src/content/[locale]/blog/*.md"
      ]
    },
    "json": {
      "include": ["src/content/[locale]/ui.json"]
    }
  }
}

O placeholder [locale] é resolvido para cada código de idioma configurado. Com source: "en", a CLI lê de src/content/en/ e grava os arquivos traduzidos em src/content/es/, src/content/fr/ e src/content/de/.

Renderize Markdoc no App Router#

Uma rota dinâmica típica carrega um documento e renderiza a árvore transformada. O repositório de demonstração expõe um helper simples:

// src/lib/markdoc.ts
export async function loadDoc(
  locale: Locale,
  collection: "pages" | "blog",
  slug: string,
) {
  const raw = await fs.readFile(
    path.join(process.cwd(), "src/content", locale, collection, `${slug}.md`),
    "utf8",
  );
  const ast = Markdoc.parse(raw);
  const frontmatter = ast.attributes.frontmatter
    ? parseFrontmatter(ast.attributes.frontmatter)
    : {};
  const content = Markdoc.transform(ast, { ...schema, variables: { frontmatter } });
  return { frontmatter, content };
}

A página do App Router é um wrapper enxuto que combina o documento com strings de UI específicas do idioma:

// src/app/[lang]/page.tsx
export default async function Home({ params }: PageProps<"/[lang]">) {
  const { lang } = await params;
  const doc = await loadDoc(lang, "pages", "home");
  const { home } = await getMessages(lang);

  return (
    <main>
      <h1>{doc.frontmatter.title}</h1>
      {renderMarkdoc(doc.content)}
    </main>
  );
}

As tags personalizadas do Markdoc (callout, bento, blog-hero etc.) são declaradas em markdoc.schema.ts e conectadas a componentes React em src/components/markdoc/. Consulte a documentação do schema do Markdoc para ver a API completa.

Detecte o idioma no middleware#

O middleware do Next.js inspeciona a requisição antes que a rota seja renderizada. Use-o para redirecionar caminhos sem prefixo para o idioma com melhor correspondência com base no cabeçalho Accept-Language:

// src/middleware.ts
export function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl;
  const hasLocale = locales.some(
    (locale) => pathname === `/${locale}` || pathname.startsWith(`/${locale}/`),
  );
  if (hasLocale) return;

  const locale = pickLocale(request); // parses Accept-Language
  const url = request.nextUrl.clone();
  url.pathname = `/${locale}${pathname === "/" ? "" : pathname}`;
  return NextResponse.redirect(url);
}

export const config = {
  matcher: ["/((?!_next|api|.*\\..*).*)", ],
};

Os visitantes chegam a /en, /es, /fr ou /de sem precisar digitar o prefixo.

Traduza localmente#

Defina sua chave de API e execute a CLI:

export LINGO_API_KEY="your-api-key"
npx lingo.dev@latest run

A CLI lê todos os arquivos que correspondem aos padrões dos seus buckets, identifica entradas ainda não traduzidas usando o lockfile, traduz apenas o delta por meio do seu engine de localização e grava os resultados no diretório de cada idioma de destino. Chaves de frontmatter, tags personalizadas do Markdoc e estruturas JSON são preservadas — só o texto traduzível muda.

Para segmentar um idioma específico durante o desenvolvimento:

npx lingo.dev@latest run --target-locale es

Automatize com GitHub Actions#

Adicione um arquivo de workflow em .github/workflows/translate.yml para traduzir a cada push:

name: Translate
on:
  push:
    branches: [main]
permissions:
  contents: write
jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Lingo.dev
        uses: lingodotdev/lingo.dev@main
        with:
          api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

Armazene sua chave de API como LINGODOTDEV_API_KEY em Settings > Secrets and variables > Actions no repositório do GitHub.

Verifique antes de fazer deploy#

Use a flag --frozen como gate de deploy para garantir que nenhum conteúdo sem tradução chegue à produção. A CLI retorna um status diferente de zero se houver qualquer entrada que precise de tradução:

npx lingo.dev@latest run --frozen

Adicione isso como uma etapa separada de CI antes do build do Next.js:

- name: Verify translations
  run: npx lingo.dev@latest run --frozen
- name: Build
  run: pnpm build

Próximos passos#