Demonstrates automated localization for a Next.js App Router site that authors long-form content in Markdoc and UI strings in JSON, with the Lingo.dev CLI (@lingo.dev/cli) push/pull flow.
Full walkthrough: lingo.dev/en/guides/markdoc-nextjs-localization
src/app/[lang]/– Next.js App Router, locale-scoped routessrc/content/en/pages/*.md,src/content/en/blog/*.md– source Markdoc content (English)src/content/en/ui.json– source UI-string catalogsrc/markdoc.schema.ts– custom Markdoc tag schema wired to React componentssrc/proxy.ts– middleware that redirects bare paths to the visitor's best-matching locale.lingo/config.json– Lingo.dev CLI configuration (two file types:markdocandjson)
# 1. Install the CLI (or prefix commands with `npx`)
npm install -g @lingo.dev/cli
# 2. Authenticate and link this repo to your engine
lingo login
lingo link
# 3. Translate changed source into every locale
lingo push --waitTranslations are committed under src/content/<locale>/… — this repo ships fully translated. After you edit English source, lingo push --wait translates only the delta. To bootstrap a brand-new locale, add it to .lingo/config.json and run lingo push --backfill-missing.
lingo push reads the source Markdoc files and ui.json, diffs them against .lingo/lock.json, and translates only new or changed entries through your linked engine. Results are written per locale into src/content/<locale>/. Frontmatter (title, description, badge), Markdoc custom tags, and JSON shape are preserved — only translatable text and whitelisted component props (e.g. label) change. Use lingo push --wait to block until results land, or run lingo push and lingo pull later.
Next.js routes under src/app/[lang]/ load the matching locale's files at request time. A middleware inspects the Accept-Language header and redirects bare paths like / or /blog/hello-markdoc to the best-matching locale.
Want translations on every push or PR without running the CLI yourself? See the CI/CD Workflows guide — the Lingo.dev GitHub App translates automatically once installed. The App reads engineId from the committed .lingo/config.json, so run lingo link and commit the updated file before installing it.
- Source:
en - Targets:
es,fr,de
pnpm install
pnpm devOpen http://localhost:3000 – you'll be redirected to /en, /es, /fr, or /de based on your browser's Accept-Language.