🌐 i18n Architecture: The Global Authority Protocol

Core Philosophy: Language is not a UI toggle; it is a physical resource path.

In Mouth Ship™, we implement URL Prefix-based i18n. This ensures that every language version of your site is a distinct, indexable asset for search engines, maximizing your global reach.

1. The "Path as Context" Strategy

We reject the use of LocalStorage-only or Cookie-only language switching because crawlers are stateless.

URL Prefixing: All routes are nested under /$lang (e.g., /en/blog, /zh/blog).
Single Source of Truth: The URL is the master state. If the user modifies the URL from /en to /zh, the entire app context shifts instantly.
Root Detection Ritual: When a user hits /, the engine executes a priority check:
1. localStorage('lng') (User preference)
2. navigator.language (Browser default)
3. siteConfig.defaultLocale (Fallback) It then executes a Hard Redirect to the appropriate prefix.

2. Atomic Translation Management

To prevent "Translation Bloat" and merge conflicts, we use an atomic folder structure in src/locales/.

Folder Hierarchy:

src/locales/[lang]/common.ts: Shared UI elements (Footers, Global Buttons).
src/locales/[lang]/nav.ts: Navigation labels.
src/locales/[lang]/home/[section].ts: Modular sections for the landing page (Hero, FAQ, etc.).

Registration Flow:

All modules are aggregated in src/i18n.ts. This centralized registry allows for automated integrity checks via npm run check-i18n.

3. SEO & Authority Synchronization

The value of URL-prefixed i18n is realized through the <SEO /> component, which automatically injects:

Hreflang Tags: Tells Google exactly which URLs correspond to which languages, preventing duplicate content penalties.
x-default: Points to the default version (usually /en/) for unmatched regions.
Dynamic HTML Lang: The <html lang="..."> attribute is updated in real-time to match the route, aiding screen readers and localized search algorithms.

4. Developer SOP: Adding New Content

Extract Keys: Never hardcode strings in JSX. Use const { t } = useTranslation('namespace').
Define in Source: Add the key to src/locales/en/....
Mirror in Targets: Immediately add the same key to src/locales/zh/....
Run Audit: Execute npm run check-i18n before committing to ensure no "Missing Key" errors in production.

Status: Engineering Protocol Active. This architecture is built for the global edge.

i18n Authority Architecture