Chapter 19: Internationalization & Localization

Two design decisions dominate everything downstream:

1. Field-level vs. document-level (entry-level) localization. Field-level keeps one document and stores translations per field; document-level creates a separate document per locale linked by a shared key. Field-level is leaner when most structure is identical across locales and only text changes — it gives a single source of truth and trivial fallback. Document-level wins when locales diverge structurally (different sections, region-specific products, legal blocks) or need independent publishing workflows. The major headless CMSs reflect this split: Payload and Sanity support both field-level and document-level with configurable fallback; Strapi ships field-level localization with 500+ pre-created locales; Contentful uses per-locale fields by default but supports per-locale spaces for stronger isolation at the cost of admin overhead (DEV/Sanity/Strapi platform docs, 2026). For a custom CMS, the pragmatic default is field-level with an explicit locale column and a fallback chain, escalating specific content types to document-level only when they genuinely diverge.

2. The fallback chain. Never render an empty page because a locale is missing a string. Resolve in order: requested locale → base language → default locale, and mark fallback content visibly in the editorial UI so it is not mistaken for "done." This is the difference between a half-translated site that degrades gracefully and one that shows blank regions.

Routing strategies: subpath, subdomain, ccTLD

Where the locale lives in the URL is a near-irreversible decision once pages are indexed. The three options:

Consensus across international-SEO sources (Weglot, gtechme, DCHost, LinkGraph) is that subdirectories are the right default: they sit under the main domain and inherit its authority, keep the operational surface small (one cert, one DNS zone, one deploy), and "work well with Next.js Middleware" for locale detection and rewriting. ccTLDs and subdomains "multiply the operational surface with more DNS zones and SSL certs," while subfolders "keep most of the stack centralized." Reserve ccTLDs for cases where legal presence, payment rails, or per-market autonomy genuinely demand separate domains.

Implementation notes for a custom CMS / Next.js:

• Put locale detection in middleware: read the path prefix first, then Accept-Language, then a persisted cookie. Detect — but never force — a redirect; let users override and persist their choice. Google's John Mueller has stated hreflang is a signal, not a directive, so don't fight the user's explicit selection.
• Keep the default locale either un-prefixed or prefixed, but be consistent. A common pattern is site.com/ for the default and site.com/fr/ for others; if you do this, make sure hreflang still lists the default explicitly.
• Slugs should be localized too (/fr/a-propos, not /fr/about) for UX and local SEO — store a per-locale slug field and maintain redirects when slugs change.

The AI translation pipeline: MT/LLM + human review + translation memory

The 2026 baseline is a hybrid pipeline, not "AI replaces translators." Surveys cited by CAT-tool vendors report ~88% of translators already use CAT tools with 30–50% efficiency gains, and the tooling has shifted from pure translation memory to LLM-assisted workflows (Trados Studio's Copilot AI Assistant, Phrase Language AI, Lokalise/Crowdin AI). The recurring finding: raw LLM calls cannot respect glossaries deterministically — "they enforce instructions probabilistically, meaning output can vary across runs" (Lokalise, AI Translation Glossary). Determinism has to come from the infrastructure around the model.

A robust pipeline for an AI-native CMS:

Source string (extracted, with context)
   │
   ▼
[1] Translation Memory (TM) lookup
   ├─ exact match  → reuse approved translation (no MT cost, instant)
   └─ fuzzy match  → pre-fill, flag for light review
   │  (miss)
   ▼
[2] MT / LLM translation
   ├─ glossary/termbase injected as constraints
   ├─ context: surrounding strings, page type, tone, screenshot/DOM if available
   └─ engine choice: DeepL / Google / GPT / Claude / Gemini (route by language pair + content type)
   │
   ▼
[3] Automated QA
   ├─ placeholder & ICU syntax checks ({count}, <b>…</b>)
   ├─ glossary enforcement / back-translation verification
   ├─ length & layout checks (pseudolocalization)
   └─ MQM-style quality estimation score
   │
   ▼
[4] Human review (risk-tiered)
   ├─ high-visibility / legal / brand → full human edit
   ├─ medium → spot review of low-confidence segments
   └─ low / fuzzy-100% → auto-approve
   │
   ▼
[5] Publish → write back to TM (the loop closes)

Engine selection. Treat the translator as pluggable. DeepL launched an LLM tuned specifically for translation; its blind tests reported outputs needing "two to three times fewer edits" than Google or GPT-4 for many language pairs. General LLMs (Claude, GPT-4o-class, Gemini) win on context, idiom, tone, and following editorial instructions, and are stronger for marketing/transcreation. A practical rule: DeepL/specialized NMT for high-volume technical strings; an instruction-following LLM for nuanced, brand, or low-resource content; route by language pair and content type. Newer research formalizes terminology-constrained MT and back-translation verification (e.g. LLM-BT, arXiv:2506.08174; dual-stage terminology-aware translation, arXiv:2511.07461) — useful when terminology consistency is contractual.

Translation memory and termbase are the durable assets. TM stores approved source→target segments and serves exact and fuzzy matches; the termbase/glossary enforces brand and domain vocabulary. Together they cut cost on every subsequent job, keep terminology consistent across 1,000 pages, and feed the LLM as deterministic constraints. In a custom CMS, store TM in your own database (segment, locale pair, hash, status, approver, last-used) so you own the asset and can use it as RAG context for the LLM step.

Glossary injection, done right. Because LLMs honor glossaries probabilistically, enforce at three points: (a) inject the relevant termbase entries into the prompt, (b) run a deterministic post-check that fails the segment if a forbidden term appears, and (c) for critical terms, back-translate and compare. Hybrid LLM+NMT setups have hit high MQM scores with these guardrails.

Human-in-the-loop, risk-tiered. Not every string deserves the same scrutiny. Auto-approve 100% TM/fuzzy matches; route only low-confidence or high-stakes segments to humans. This is where MQM-style quality estimation pays off — it tells the workflow which segments need eyes.

hreflang and international SEO

hreflang tells search engines which localized URL to serve to which audience. Google's own documentation and the 2025–2026 SEO guides converge on a strict set of rules:

• Reciprocal and self-referencing. Every page lists all its alternates including itself; the set of <link> elements is identical on every variant. If A links to B, B must link back to A.
• Absolute URLs only. https://site.com/fr/contact, never /fr/contact.
• Correct codes. ISO 639-1 language, optional ISO 3166-1 alpha-2 region: en, en-US, fr-CA.
• x-default. Add one hreflang="x-default" pointing to the fallback users land on when no locale matches — typically your default-language or language-selector page. It is "insurance against uncertainty."
• Where to put it. Three delivery methods: <link> in <head> (most common), HTTP Link headers (for non-HTML like PDFs), or an XML sitemap (best at very large scale — see scaling below). Pick one method per URL; don't mix conflicting signals.

Minimal example for three locales plus default:

<link rel="alternate" hreflang="en-us" href="https://site.com/about" />
<link rel="alternate" hreflang="fr-fr" href="https://site.com/fr/a-propos" />
<link rel="alternate" hreflang="ar"    href="https://site.com/ar/about" />
<link rel="alternate" hreflang="x-default" href="https://site.com/about" />

For an AI-native CMS, generate hreflang programmatically from the locale model and the per-locale slug table — manual maintenance across 1,000 pages and N locales is the single most common source of broken international SEO. Validate continuously (Screaming Frog, Ahrefs, or a CI check) because a single non-reciprocal link can cause Google to ignore the cluster.

RTL and bidirectional layout

Roughly a fifth of the world reads right-to-left (Arabic, Hebrew, Persian, Urdu). RTL is not "flip everything" — it is mirroring layout while keeping numbers, code, and embedded LTR strings correct. The 2026 consensus is to design direction-agnostically from the start using CSS logical properties rather than retrofitting.

Core techniques:

• Set direction at the root, per page. <html lang="ar" dir="rtl">. The lang and dir attributes must reflect the rendered locale; drive both from the locale model.
• CSS logical properties instead of physical ones. Use margin-inline-start / margin-inline-end, padding-inline-*, border-inline-*, inset-inline-*, and text-align: start | end instead of left/right. These flip automatically with dir, so one stylesheet serves both directions. Browser support is excellent in 2026 — "safe to use without fallbacks." Flexbox and Grid also reverse automatically under dir="rtl".
• Mirror icons and directional UI (back/forward arrows, progress, breadcrumbs) but do not mirror logos, media controls play buttons, or charts with intrinsic direction.
• Bidi correctness. Wrap embedded opposite-direction runs (a Latin brand name in Arabic text, phone numbers) with <bdi> or Unicode isolates to prevent reordering glitches. Set letter-spacing: 0 for Arabic — its letters connect and spacing breaks the script.
• Test with real content, not Lorem Ipsum. RTL bugs are layout bugs (clipped text, misaligned form labels, reversed paddings) that only surface with actual Arabic/Hebrew strings. Pseudolocalization that injects RTL markers helps catch these in CI before translators are involved.

Frameworks help: Tailwind's RTL variants and logical-property utilities, and component libraries with built-in RTL (Untitled UI, Flowbite, MUI) reduce manual work — but the discipline is yours.

Locale-aware formatting: Intl, CLDR, and MessageFormat 2

Never hand-format dates, numbers, or currencies. The browser and Node already ship the world's locale data via Unicode CLDR ("all major browsers and modern phones use CLDR"), exposed through the standard Intl API (ECMA-402):

• Intl.NumberFormat(locale, { style: 'currency', currency: 'EUR' }) — handles grouping separators, decimal marks, and currency placement per locale (ISO 4217 codes).
• Intl.DateTimeFormat(locale, {...}) — resolves dd/mm vs. mm/dd, calendars, and time zones.
• Intl.RelativeTimeFormat, Intl.ListFormat, Intl.PluralRules, Intl.Collator — relative times, lists, plural categories, and language-correct sorting.

For interpolated, pluralized, and gendered UI strings, use MessageFormat 2 (MF2). The Unicode MF2 spec reached Stable status in CLDR 47 (March 2025) and continues to evolve (LDML 48, October 2025); the JS messageformat 4.0 library provides an MF2 formatter plus a polyfill of the runtime API proposed for ECMA-402. MF2 replaces brittle string concatenation with a single message that encodes plural and select logic — critical because plural rules differ wildly (English has 2 categories, Arabic has 6, Polish 4). Store source messages in MF2/ICU syntax, validate placeholder integrity in your QA step, and never let translators "translate around" a placeholder.

A subtle point for AI pipelines: ICU/MF2 syntax must survive the LLM. Lock placeholders ({count}, {name}) as non-translatable tokens, pass them through verbatim, and fail QA if the count or names change.

Scaling localization across 1,000+ pages

At small scale, manual translation in the CMS works. Past a few hundred pages and a handful of locales, you need continuous localization — the same CI/CD discipline applied to content.

The architectural payoff of doing locale modeling, externalized strings, and a TM-backed pipeline correctly is exactly this: adding the 25th locale or the 5,000th page is a configuration and budget question, not an engineering project. That is the entire promise of i18n done up front.

Key Takeaways

• Separate i18n (one-time architecture) from l10n (recurring per-locale work); retrofitting i18n after launch is the expensive failure mode.
• Model the locale as a first-class BCP 47 entity with direction, fallback chain, currency, and slug — not a string scattered through the codebase.
• Choose field-level localization by default, escalate to document-level only where locales structurally diverge; always define an explicit fallback chain so pages never render empty.
• Subdirectories (/fr/) are the right default routing strategy for most sites — they inherit domain authority and minimize operational surface; reserve subdomains/ccTLDs for governance or legal isolation.
• Build a hybrid AI translation pipeline: TM-first → MT/LLM with injected glossary → automated QA → risk-tiered human review → write back to TM. LLMs honor glossaries probabilistically, so enforce terminology deterministically in the infrastructure.
• Generate hreflang (reciprocal, absolute URLs, self-referencing, with x-default) programmatically from the locale model — manual maintenance is the top cause of broken international SEO.
• Support RTL with CSS logical properties and dir/lang from day one, test with real Arabic/Hebrew content, and use <bdi>/isolates for embedded LTR runs.
• Defer all date/number/currency formatting to Intl/CLDR, and use MessageFormat 2 (stable since CLDR 47, March 2025) for plurals and gender; protect placeholders through the AI step.
• Adopt continuous localization (webhook-driven, TM-backed, pseudolocalized in CI) so adding locales or pages scales as configuration, not engineering.

Key References

• Weglot. The Only Guide You Need to Website Internationalization. 2025. https://www.weglot.com/guides/website-internationalization — Defines i18n vs. l10n as architectural work; routing and content-model guidance.
• gtechme. International Website: Subdomains vs. Subdirectories vs. ccTLDs. 2025. https://www.gtechme.com/insights/international-website-structure-cctld-vs-subdomain-vs-subdirectory/ — Trade-off analysis favoring subdirectories for SEO authority.
• Google Search Central. Localized Versions of your Pages (hreflang). 2025. https://developers.google.com/search/docs/specialty/international/localized-versions — Authoritative hreflang rules: reciprocity, self-reference, x-default, delivery methods.
• LinkGraph. Hreflang Implementation Guide (2026). 2026. https://www.linkgraph.com/blog/hreflang-implementation-guide/ — Absolute-URL requirement, code standards, large-scale sitemap delivery.
• Lokalise. AI Translation with Glossary Support: Deterministic Terminology for LLMs. 2025. https://lokalise.com/blog/ai-translation-glossary/ — Why LLMs honor glossaries only probabilistically; infrastructure-level enforcement.
• Lokalise. What is the best LLM for translation?. 2025. https://lokalise.com/blog/what-is-the-best-llm-for-translation/ — Comparison of GPT, Claude, Gemini, DeepL for translation by content type.
• Crowdin. Continuous Localization Guide for Websites and Apps. 2025. https://crowdin.com/blog/continuous-localization — Webhook-driven, Git-integrated continuous localization patterns at scale.
• Crowdin. CMS Translation: Scalable Localization for Developers. 2025. https://crowdin.com/blog/cms-translation — Field vs. document localization and CMS integration approaches.
• The Unicode Blog. Unicode CLDR 47 Release: MessageFormat 2.0 Stable. March 2025. http://blog.unicode.org/2025/03/unicode-cldr-47-release-messageformat-2.html — MF2 reaching Stable status; CLDR as the locale-data backbone.
• MDN Web Docs. Intl namespace (ECMAScript Internationalization API). 2025. https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl — Intl.NumberFormat/DateTimeFormat/PluralRules reference.
• rtlstyling.com. Right to Left Styling 101. 2025. https://rtlstyling.com/posts/rtl-styling/ — Practical RTL with CSS logical properties, bidi, mirroring rules.
• MDN Web Docs. direction CSS property. 2025. https://developer.mozilla.org/en-US/docs/Web/CSS/direction — Direction handling and logical-property behavior.
• DEV Community (Golchian). Headless CMS 2026: Contentful vs Strapi vs Sanity vs Payload Compared. 2026. https://dev.to/pooyagolchian/headless-cms-2026-contentful-vs-strapi-vs-sanity-vs-payload-compared-5bi3 — Localization models across major headless CMSs.
• DeepL / getBLEND. Best LLMs for Translation in 2025. 2025. https://www.getblend.com/blog/which-llm-is-best-for-translation/ — DeepL specialized translation LLM and edit-rate comparison.
• arXiv:2506.08174. LLM-BT-Terms: Back-Translation for Terminology Standardization. 2025. https://arxiv.org/pdf/2506.08174 — Back-translation framework for deterministic terminology verification.