Next.js Localization Example

Demonstrates localizing a Next.js (Pages Router) app at the source level with the Lingo.dev CLI (@lingo.dev/cli) and @lingo.dev/react-next. Wrap UI strings in l.text(...) with context, run lingo extract to generate a hash-keyed catalog, then lingo push to translate. Next.js i18n routing serves each locale under its own path (/, /es, /fr, /de).

Full walkthrough: lingo.dev/en/guides/web-app

What's inside

• src/pages/_app.tsx — withLingoApp + LingoHead (provider wiring + hreflang tags)
• src/pages/index.tsx — page UI with useLingo().text(...), withLingoProps({ route }), and a locale switcher (useLocaleSwitch)
• next.config.ts — Next.js i18n routing
• locales/*.jsonc — extracted (en) and translated (es/fr/de) catalogs
• lingo.d.ts — generated types that make context required at compile time
• .lingo/config.json — Lingo.dev CLI configuration

Quick start

pnpm install

# Authenticate and link this repo to your engine
lingo login
lingo link

# 1. Extract strings from l.text() calls → locales/en.jsonc + lingo.d.ts
lingo extract

# 2. Translate the catalog into every target locale
lingo push --wait

# 3. Run it, then visit /, /es, /fr, /de
pnpm dev

Catalogs are committed under locales/. This repo ships fully translated. After you add or edit an l.text(...) call, re-run lingo extract then lingo push --wait. To bootstrap a brand-new locale, add it to both next.config.ts and .lingo/config.json, then run lingo push --backfill-missing.

How it works

Strings live in code, not in translation files:

const l = useLingo();
<p>{l.text("Track every expense, in every currency.", { context: "Hero tagline" })}</p>

lingo extract scans the source, hashes each (source + context) pair into a stable key, and writes locales/en.jsonc plus lingo.d.ts (which makes context a required argument — TypeScript fails the build if you forget it). lingo push translates the catalog into locales/<locale>.jsonc.

At request time, withLingoProps({ route }) loads the page's messages for the active locale (Next.js resolves the locale from the URL), and withLingoApp serves them to useLingo(). LingoHead emits hreflang tags, and useLocaleSwitch changes locale by navigating to the localized route.

Automate in CI (optional)

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.

Locales

• Source: en
• Targets: es, fr, de

Links

• Guide: Web App Localization
• Lingo.dev CLI docs
• Create a free account