Multilingual i18n Architecture — Scope Explainer

What it means & why it matters

What SessDev includes

• Locale-prefixed routing (e.g. /en/* and /es/*) with a configured default locale and a deterministic redirect policy for the root path.
• Per-locale message catalogs (one JSON file per language) structured so a translator can edit a single file without touching code.
• Locale switcher component wired to preserve the user's current route when switching languages.
• hreflang alternate links emitted on every localized page, including x-default pointing to the configured default locale.
• Page title, description and Open Graph metadata localized per locale through the same message-file pipeline.
• Documented fallback policy for missing keys: which locale serves as fallback, and whether a missing key fails the build or logs at runtime.
• Build-time check that every key present in the default locale exists in every other agreed locale; missing keys break the build, not production.
• Support for ICU MessageFormat: variables, plurals and basic rich-text formatting, so translators do not have to fork strings per number or gender.
• 1 recorded walkthrough for the team or translator covering how to edit message files, add a new key, and verify a translation before publishing.

What is excluded

• Translation of UI strings or page copy into any language; the client supplies translated text per locale.
• Localized copywriting, headline rewriting or value-proposition adaptation per market.
• Cultural adaptation, idiomatic rewrites or brand-voice tuning per region.
• Glossary management, terminology bases, translation memory or per-vendor TMS integrations.
• Locales beyond the set agreed at scope time. Adding a new language post-launch is a separate scoped change.
• Machine-translation pipelines (DeepL, Google Translate, LLM-based) wired into the build or runtime.
• Per-region SEO strategy (es-MX vs es-ES, en-US vs en-GB targeting, regional keyword research).
• Currency conversion, regional pricing display, tax-inclusive formatting or per-market price tables.
• Localized legal text per jurisdiction; the client supplies the legal copy for every locale, vetted by their counsel.
• Per-market regulatory compliance (cookie law variants, accessibility standards beyond WCAG AA, data-residency obligations).
• Ongoing editorial operations: scheduling, reviewing or proofreading translations after handoff.

Risks if this is mis-configured

• Missing-key runtime errors

  If a translator adds a new key in one locale and forgets the other, the page can crash at runtime with MISSING_MESSAGE. Build-time validation catches this in CI, but only if the validation step is kept enabled.

• Drift between locales

  When one language is updated faster than the others, the site silently ships with stale copy in the lagging locales. Users in those markets read out-of-date information; the team rarely notices until a customer complains.

• hreflang mismatch

  If hreflang points to URLs that 404 in the other locale, Google ignores the entire cluster. The site appears to lose international visibility for no obvious reason; the cause is one missing translated route.

• Length overflow in UI

  German, Finnish and many Latin American Spanish phrasings run 30–60% longer than English. Buttons wrap, menus overflow, hero copy breaks the grid. Designs validated only in English ship visually broken in other locales.

• Fallback misconfiguration

  A misconfigured fallback chain can serve the wrong language, loop between locales, or render empty strings. The user sees an unfinished page; analytics records the visit as a bounce.

• Legal divergence between languages

  If the English legal page is updated and the Spanish one is not, the client is bound by different terms in different languages. This is a real legal exposure, not a UX bug.

• Locale scope bleed

  'Just add German' after launch sounds small; it doubles QA, multiplies translation cost, expands SEO surface and forces a re-audit of every page. Adding locales must be a scoped change, not an ad-hoc request.

Related scope items

• content_injectionTranslated strings supplied by the client are injected through the same message-file pipeline.
• cms_blog_setupThe CMS schema can be modeled as multilingual, but post translation is excluded just like UI translation.
• technical_seohreflang, localized canonical and per-locale sitemaps are coordinated with the technical SEO layer.
• legal_pages_setupLegal pages support multiple locales structurally, but the legal copy per language is client-supplied and vetted by their counsel.
• analytics_integrationAnalytics segments by locale so traffic and conversion can be compared across languages.
• media_infrastructureLocale-aware media (region-specific imagery, localized assets) is supported by the media pipeline but is not produced by SessDev.

Frequently asked questions

Which languages are included by default?

The locales agreed at scope time. SessDev does not pre-bundle a default language list; the set is fixed before implementation and frozen in the build.

Can we add another language after launch?

Yes, as a separate scoped change. Adding a locale requires routing updates, hreflang reconciliation, message-file migration, QA per page and SEO re-validation — none of which is in the original scope.

Does SessDev translate the content?

No. SessDev integrates translated strings supplied by the client. Hiring translators, running review cycles and maintaining a glossary belong to the client or a partner translation agency.

Can we wire machine translation (DeepL, Google, an LLM)?

Out of scope by default. SessDev can scope it as a separate integration, but the quality, legal and brand risks of unreviewed machine output remain with the client.

What happens if a translation is missing when we deploy?

Build-time validation flags missing keys and fails CI before the broken build reaches production. The default policy is fail-the-build; opting into runtime fallback instead is a documented client decision.