feat: i18n with `next-intl` + per-locale MDX content (`content/<slug>/<locale>.mdx`)

[bntvllnt]

Problem

Site is English-only. Two costs:

1. SEO — non-English markets don't index us; `hreflang` alternates absent.
2. AI agents — agents querying in non-English contexts get nothing back.
3. Brand reach — VLLNT readership is global; English-only is a self-imposed ceiling.

Goal

First-class internationalization, leveraging existing MDX content pipeline. Co-locate translations next to source MDX — no separate translation tree.

Architecture (file layout)

apps/registry/
├── i18n/
│   ├── routing.ts        ← next-intl config: locales, defaultLocale, localePrefix
│   └── request.ts        ← message loader (per-request locale resolution)
├── messages/
│   ├── en.json           ← UI strings (chrome, buttons, search, errors)
│   ├── fr.json
│   └── es.json
├── app/
│   └── [locale]/         ← all routes under here
│       ├── page.tsx
│       ├── components/...
│       ├── docs/...
│       └── ...
└── content/
    └── pages/
        ├── home/
        │   ├── en.mdx
        │   ├── fr.mdx
        │   └── es.mdx
        ├── docs/installation/
        │   ├── en.mdx
        │   └── fr.mdx
        ├── philosophy/
        │   ├── en.mdx
        │   └── fr.mdx
        └── design/
            ├── en.mdx
            └── fr.mdx

Convention: every routable MDX page lives in a folder named for its slug, with one file per locale. The MDX loader in `page.tsx` resolves `/.mdx`, falling back to `/en.mdx` if the locale file is missing.

Library choice

`next-intl` — decision locked.

• Native App Router support.
• Locale-prefixed routes (`/fr/components/button`) with `localePrefix: 'as-needed'` (English at root, others prefixed).
• Server Components first.
• ``, `useRouter`, `usePathname` wrappers for locale-aware navigation.
• Mature, actively maintained, used in production at scale.

Alternatives considered + rejected: `next-i18next` (Pages Router era), `@lingui/core` (heavier toolchain), DIY (not worth it).

Initial locales

Phase 1: `en` + `fr` (founder-quality translations possible).
Phase 2: `es`, `de`, `pt-BR`, `zh-CN` (community / AI-assisted, reviewed before merge).

Acceptance criteria

Routing & config

• `i18n/routing.ts` defines `locales`, `defaultLocale: 'en'`, `localePrefix: 'as-needed'`.
• `i18n/request.ts` loads messages per request locale.
• All routes moved under `app/[locale]/`.
• `middleware.ts` configured with `createMiddleware(routing)` for locale negotiation.
• Custom ``, `useRouter` wrappers re-exported from `@/i18n/routing`.

MDX pipeline

• `content/pages//` folder convention adopted; existing `home.mdx`, `philosophy.mdx`, `docs.mdx`, `components.mdx` moved to `/en.mdx`.
• MDX loader resolves `content/pages//.mdx` with English fallback.
• `generateStaticParams` enumerates `(locale, slug)` for static generation.

UI strings

• `messages/en.json` extracted from current header/footer/search/buttons.
• `messages/fr.json` translated.
• All hardcoded JSX strings replaced with `useTranslations()` keys (codemod or manual).

SEO

• Per-page `generateMetadata` emits `alternates.languages` map with hreflang for every locale.
• Canonical points to current locale URL (seo: add canonical URLs + alternates to per-page generateMetadata #237).
• Sitemap (seo: add app/sitemap.ts enumerating routes + 225 component pages #234) emits one entry per locale per route.
• `/llms.txt` (ai-agents: serve /llms.txt per llmstxt.org spec #235) lists `/fr/llms.txt` and similar variants.
• Hreflang `x-default` points to English version.
• OG `locale` and `localeAlternate` set per page.

Component pages

• `/components/[slug]` works under each locale.
• Component descriptions in `registry.json` get a `descriptions` map: `{ en, fr, ... }`. Falls back to `description` (English) when locale missing.
• `/r/.json` keeps English as canonical (registry contract); locale UI text comes from a separate `/r/..json` overlay (additive, optional).

Locale switcher

• Header gets a locale switcher (lucide `Languages` icon).
• Switching preserves the current path.
• Persisted via `NEXT_LOCALE` cookie + URL prefix.

CI

• CI step verifies every `/en.mdx` has a non-empty translation in every active locale (or graceful fallback annotated).
• Missing translation = warning (not error) for non-English locales.

Out of scope

• Right-to-left languages (separate issue once `ar` / `he` added).
• Component-level RTL flag (mentioned in ai-agents: ship @vllnt/mcp — MCP server (search/get/install components) #246 / ai-agents: add per-component accessibility schema to /r/<name>.json #255 — track separately).
• Dictionary-based UI strings (`messages/.json` is enough for v1).

Depends on

• seo: add app/sitemap.ts enumerating routes + 225 component pages #234 (sitemap — needs hreflang awareness)
• seo: add canonical URLs + alternates to per-page generateMetadata #237 (canonical — needs locale variant)
• seo: add JSON-LD structured data (Organization, WebSite, SoftwareSourceCode) #238 (JSON-LD — `inLanguage` field per page)
• ai-agents: serve /llms.txt per llmstxt.org spec #235 (llms.txt — locale-prefixed variants)

References

• next-intl: https://next-intl-docs.vercel.app
• Next.js i18n routing: https://nextjs.org/docs/app/building-your-application/routing/internationalization
• hreflang: https://developers.google.com/search/docs/specialized/international/localized-versions

Success metrics

• Google Search Console: indexed pages × locale count after 30 days.
• `hreflang` validator: zero errors on https://www.aleydasolis.com/english/international-seo-tools/hreflang-tags-generator/.
• Lighthouse SEO ≥ 95 in each locale.