Arkian logo
Start free
Menu
← All articles

Locale Fallback Strategy: How to Build Chains That Work

Locale Fallback Strategy: How to Build Chains That Work

Engineer testing incomplete regional language support

A good locale fallback strategy is an ordered chain, not a single default. You decide, for each locale you support, which locales to try next, you keep one complete base language, and you finish at a default that is always fully translated. Stripping subtags is a reasonable starting point, but it is not a policy. This guide shows how to design the chain, where truncation goes wrong, and how to name keys so fallback stays predictable.

Arkian
Keep Localization Outputs Fallback-Ready
Arkian automates multilingual scripts, voice outputs, and structured language packages, helping small teams organize localization without complex TMS workflows.
Explore Arkian

TL;DR

  • Model fallback as a list per locale (exact, regional parent, base language, default), not as “missing means English.”
  • Keep one complete file per base language and put only regional differences in variant files.
  • Add explicit exceptions where hyphen stripping picks the wrong neighbor, such as es-MX to es-419 or Chinese script variants.
  • Treat messages, routes and formatting as three separate fallback decisions, and treat browser language as a hint the user can override.
  • Name keys by meaning and place, never by English text, so a fallback hit is always the same string in every language.

Table of Contents

What a fallback chain is, and why one default is not enough

When a user asks for a locale you have not fully translated, something has to be shown. The simplest rule, “show English,” works until you ship your fifth language. A Chilean Spanish user then sees English buttons next to Spanish menus, even though you have complete Spanish for Spain.

The standards agree on the better shape. RFC 4647, published in September 2006, describes lookup as picking the best match from a prioritized list, progressively truncating the requested tag and returning a configured default only when nothing matches. Mozilla’s locale documentation takes the same view that matching is always best-effort, so you cannot assume a perfect match exists.

So write the chain down. For a request of es-CL, an explicit policy might read:

  1. es-CL (exact)
  2. es-419 (Latin American Spanish, if you have it)
  3. es (base Spanish)
  4. en (default, fully covered)

That is a product decision. Mozilla’s background notes make the same point: the exact sequence should reflect your language policy rather than blind subtag stripping.

Two stages: negotiate, then fall back

There are two separate questions, and mixing them causes most bugs.

Negotiation is about the user. They have an ordered list of preferences, such as fr-CH, then de-CH, then en. Fuchsia’s documentation separates this language matching from fallback and allows up to 10 preferred locales. Mozilla recommends representing even a single requested locale as a list, so you can extend it later without changing the API.

Fallback is about your resources. Given one locale the user wants, which of your files can stand in for it? Fuchsia’s example: a requested en-US can fall back to en, while a user can separately name en-US as a later preference.

In practice, negotiate first to pick the best locale you ship, then resolve each missing key along that locale’s chain. Neither a hardcoded English fallback nor automatic parent stripping alone captures what the user wants. An ordered preference list plus deterministic resource fallback does.

Locale preference negotiation and resource fallback

Where hyphen stripping goes wrong

The default algorithm in many libraries is truncation. Microsoft’s globalization guidance documents the ICU sequence: remove the variant, then the country, then the script, then use the default locale if the language still does not match.

That works for fr-CA to fr. It fails when the shortest tag is not the closest language. The same Microsoft page notes that es-MX may be better served by es-419 than by generic es, and the Unicode CLDR language distance proposal exists because matching by “closeness” beats a plain truncation algorithm.

Three exceptions most small teams eventually write down:

Requested Naive result Better explicit chain
es-MX, es-AR, es-CO es es-419, then es
zh-TW, zh-HK zh (often Simplified) zh-Hant, then your default
pt-AO pt (maybe pt-BR) pt-PT, then pt

The Chinese row matters most. Script is not a detail: Traditional and Simplified are not interchangeable to readers. The CLDR likely subtags data shows how zh with Taiwan information resolves toward Traditional Chinese and Taiwan. That data is heuristic and can change between versions, so pin your library and CLDR versions and run a small test of representative locale pairs whenever you upgrade.

The pt-AO row is our illustration of the pattern rather than a rule from a standard: check it with a native reviewer before you adopt it.

Base language plus regional overrides

The most maintainable file layout is a complete base file for each language, with thin regional files that contain only the differences. i18next’s fallback principles recommend exactly this: shared text lives in the pure language resource, and variant files hold only regional differences. Fallback languages can be mapped globally, per region or dynamically, and the library also supports fallback namespaces, fallback keys and default values. That gives you four places to catch a gap: language, namespace, key and value.

Android pushes the same idea. Its multilingual support documentation recommends keeping common resources in a parent dialect such as Latin American Spanish instead of duplicating region-specific files. It also shows what happens without careful structure: with only default en_US strings and Spanish under es_ES, a device set to another Spanish region may fall to English, because the system cannot find an exact match. Android 7.0 and later resolve to a closer parent dialect more robustly, for example fr_CH to fr_FR when neither fr_CH nor fr exists, rather than jumping to the default.

A layout that follows this:

locales/
  en.json        # complete, the production default
  es.json        # complete base Spanish
  es-419.json    # only keys that differ
  es-MX.json     # only keys that differ from es-419
  fr.json
  fr-CA.json     # only differences

If you want to see how output folders can be organized for this, our multilingual output folder structure page lays out one approach, and our post on resource bundle localization covers keeping bundles from breaking.

Do not use the developer language as the production fallback

i18next advises using an existing, real language as the production fallback, rather than the developer language used to collect missing keys. In other words, your fallback should be a language you have reviewed completely. If your source strings are rough drafts, a fallback to them is a bug you ship to every user with an incomplete locale.

Fallback is more than strings

A fallback policy that covers only message lookup leaves three gaps.

Formatting, currency and compliance

Microsoft’s guidance makes a point that is easy to miss: the closest language is not always the closest locale. A French Canadian user may be linguistically close to French from France, yet keyboard, address and regional conventions differ. Keep language fallback separate from date, number, currency, address and legal decisions. Falling back to German text for a user in Austria should not change the currency or the terms they accept.

Routes and pages

For websites, you also have to decide what happens to the URL. Astro’s internationalization docs split this into two independent choices: which locale supplies the missing content, and whether the app redirects to that locale or rewrites the fallback content under the requested URL. That option arrived in Astro v4.15.0.

The SEO consequences differ. A redirect tells crawlers the page lives elsewhere. A rewrite serves one language under another locale’s URL, which can look like duplicate content. For pages that matter for search, many teams decide that a missing translation should not exist as a URL at all. If you manage alternate-language annotations, automating them on every change helps; this write-up on regenerating hreflang in CI/CD shows one way to keep them in sync with what you actually publish.

Browser language is a hint

W3C guidance explains that Accept-Language was meant to express a language, yet applications use it to guess a locale. An es-MX header does not prove the user lives in Mexico or wants Mexican address or validation rules. Use it as the first guess, offer a visible language selector, and persist the user’s choice separately. The W3C site conneg note adds a useful detail: a preference list should put a less specific tag after a regional one, such as fr-CH followed by fr, and a site should define a default for when nothing matches.

Key naming and fallback: how they interact

Fallback only works if the same key means the same thing in every file. That is where i18n key naming earns its place.

Name by meaning and location, not by English copy. A key like checkout.payment.submit survives a copy change. A key like Place your order breaks in every locale when marketing rewords the button, and fallback will quietly show a stale string.

Keep a stable hierarchy. Namespace by feature or screen: settings.notifications.title, onboarding.step2.cta. This pairs well with namespace-level fallback.

One concept, one key. Do not reuse a key for two different meanings because the English word is the same. Languages split what English merges.

Do not encode locale in the key. Regional differences belong in variant files, not in title_mx. Variant files keep the chain doing its job.

Make missing keys visible in development. One open-source project discussion about debuggable missing-key fallback describes the pain of a runtime that returns a bare placeholder with no clue which key failed. Log the key and the locale chain that was tried, and fail loudly in tests while staying graceful in production.

Plurals and placeholders are the next place keys break. Our short guides on ICU message format checks and batch translating strings cover keeping them intact across languages.

Key naming and fallback: how they interact — overview diagram

A fallback policy a small team can maintain

You do not need a localization department to do this well. A workable policy fits on one page:

  1. Pick a fully covered default. One language, reviewed, 100 percent of keys. Release gates check this.
  2. List supported locales and mark each as base or regional. Regional files hold only overrides.
  3. Write the chain for every locale. Include explicit exceptions (es-419, zh-Hant) rather than trusting truncation.
  4. Decide formatting separately. Currency, date and address rules are not part of text fallback.
  5. Decide the route behavior. Redirect, rewrite or no page, per content type.
  6. Persist user choice. Selector visible, choice stored, header only as the first guess.
  7. Test the chain. For each locale, delete a key and assert what appears. Re-run after every library or CLDR upgrade.

A worked example

Say you ship en, es, fr and zh-Hans, and a user arrives with es-CL, en. Your es-CL file does not exist. The chain for es-CL is es-419 (not present), then es (present, 98 percent complete). Two keys are missing in es, so those two resolve to en, the default. The user sees Spanish almost everywhere and English in two places, and your log records both keys. That is a healthy outcome. Compare it with a global “missing means English” rule, which would show English everywhere because there was no exact match.

Now the same user switches to zh-TW. You have no Traditional Chinese. Falling to zh-Hans would be a silent mismatch of script, so your policy may instead say: show the default, and offer the selector. Either choice is defensible, but it should be a choice someone wrote down.

Perspective: fallback is a contract, not a hope

We build localization for small teams that do not have a translation management system or a dedicated localization engineer. In that setting, we see the same pattern: fallback behavior is decided by whatever the runtime does by default, and nobody writes it down until a user screenshot arrives.

Our view is that fallback belongs in the deliverable, next to the strings. Android, ICU and web frameworks resolve missing content differently, and some also change URLs or build output. So a package should say what it expects: the base language, the regional overrides, the chain and the default. Then the files, not the memory of one developer, carry the contract.

We also think completeness should be checked before release, not discovered afterward. A validated package, with every key present in the default and variants reduced to real differences, makes fallback a safety net you rarely touch instead of the main way text reaches users.

— Arkian

Producing fallback-ready language files with Arkian

If you would rather not hand-assemble this, Arkian generates and packages localized app strings into reviewable, delivery-ready files, including JSON, iOS .strings and Android XML, without needing access to your repository or a full TMS. Our structured packaging service validates and organizes the output so your base files and regional files arrive consistent. Our membership is 19.00 CAD per month, and one-off packs are Starter at 29.00 CAD, Pro at 79.00 CAD and Studio at 249.00 CAD. See the details on the pricing page.

FAQ

What is the difference between a locale fallback and a language fallback?

In everyday use they overlap. Strictly, locale fallback moves from a specific locale such as fr-CA to a more general one such as fr, while a language fallback can jump between languages, such as from a minority language to a regional lingua franca. Write both into the same ordered chain, and keep formatting rules separate from text.

Should my fallback always be English?

Only if English is your fully reviewed, complete language. A good chain tries a regional parent and a base language first, and ends at a default that covers every key. i18next advises a real, existing language as the production fallback, not the developer language used to collect missing keys.

Is removing the region subtag enough?

It is fine for many pairs, such as fr-CA to fr. It can choose a less suitable language for cases like es-MX, where es-419 may serve users better than generic es, and for Chinese, where script matters. Add explicit exceptions for these and test them.

Can I trust the browser’s Accept-Language header?

Use it as a first guess only. W3C notes it does not reliably reveal a user’s full locale or location, so provide a visible language selector and store the user’s choice.

How do I name i18n keys so fallback stays reliable?

Name keys by meaning and place, such as settings.notifications.title, not by the English sentence. Keep one concept per key and put regional differences in variant files, not in key suffixes. That way a fallback hit is always the same intended string.

Sources