Locale-aware i18n routing (next-intl)

Definition

Locale-aware routing is a routing model where the user's chosen language (ko/en/ja) is reflected consistently across all internal URLs and client-side navigation.

With next-intl and localePrefix: "always", URLs always look like /ko/til or /en/knowledge/.... Paths without a prefix — such as /til — are 301-redirected by middleware to the default locale (e.g. /ko/til).

Why it matters

Content may exist in en/ja, but if the header, sitemap, and cards use plain next/link pointing at /til, every click from /en sends users through middleware to /ko/til, resetting language choice each time. That is a routing contract violation, not a translation quality issue.

By contrast, Link and useRouter from @/i18n/navigation automatically include the current locale in hrefs. Sampling SSR HTML href values quickly catches bare-path regressions.

How it works

1. Middleware: With localePrefix: "always", detect bare pathnames and redirect to the default locale.
2. i18n Link: href="/til" renders as /en/til (based on current locale).
3. Plain next/link: href="/til" stays bare → middleware 301 → /ko/til.
4. Language switcher: Use routing.locales as the single source for dropdown, sitemap, and message keys.
5. Programmatic nav: Use the i18n router for router.push and replace. Works alongside startTransition and view transitions.
6. Markdown body links: Apply locale prefix conversion in the remark pipeline (separate from app shell Link).

// Internal navigation — OK
import { Link } from "@/i18n/navigation";
<Link href="/knowledge">Knowledge</Link>;

// Forbidden for internal navigation with localePrefix always
import NextLink from "next/link";
<NextLink href="/knowledge">Knowledge</NextLink>;

Practical application

• Grep content-nav, footer, list cards, and breadcrumbs; remove internal next/link usage.
• Replace per-page copy-pasted untranslated fallback with getLocalizedDocumentOrRedirect helper + tests.
• After prod next start, curl /en/... HTML and count internal hrefs — target zero bare paths.
• Pass active locale as query param or header to load-more and relations APIs.
• Add an ESLint custom rule or codemod to flag new from "next/link" imports under src/.

Trade-offs

When not to use

• External sites, mailto:, and absolute URLs — plain <a> or next/link with full URL is locale-agnostic.
• API routes and static assets — no locale segment.
• localePrefix: "never" policy — different premise from this document's always assumption.

Common mistakes

• Converting only the header to i18n Link while 12 content-nav spots still use plain next/link.
• Adding locale prefix only on the client while SSR HTML stays bare → SEO and no-JS users land on ko.
• Expecting view transitions on router.back() — popstate is synchronous, so VT is unsupported (use explicit URL push).
• Shipping markdown body links like ../knowledge/... without a locale conversion pipeline.

Related concepts

• multilingual-content-locale-suffix — content locale axis
• hierarchical-document-navigation — list → detail depth
• ssr-hydration-mismatch — SSR HTML and client href alignment