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
src/pages/_app.tsx—withLingoApp+LingoHead(provider wiring + hreflang tags)src/pages/index.tsx— page UI withuseLingo().text(...),withLingoProps({ route }), and a locale switcher (useLocaleSwitch)next.config.ts— Next.js i18n routinglocales/*.jsonc— extracted (en) and translated (es/fr/de) catalogslingo.d.ts— generated declarations that narrowl.text()to the extracted strings and their contexts.lingo/config.json— Lingo.dev CLI configuration
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 devCatalogs 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.
Strings live in code, not in translation files:
const l = useLingo();
<p>{l.text("Track every expense, in every currency.", { context: "Hero tagline under the app title" })}</p>;lingo extract scans the source, hashes each (source + context) pair into a stable key, and writes locales/en.jsonc plus lingo.d.ts. context is a required argument either way — what the generated declarations add is narrowing: l.text() only accepts strings you have extracted, each with the exact context it was extracted under, so a typo in either fails the build. 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.
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