Fallback chain

An ordered sequence of locales that an application works through when a translation for a specific string is missing, moving from most specific to most general until it finds a match.

When a user’s requested locale does not have a translation for a given key, the application does not stop there. It moves to the next locale in a predefined sequence, checking each one in order until it finds a valid translation or reaches the end of the chain. That sequence is the fallback chain.

The pattern almost always runs from specific to general. A user with their device set to de-CH (Swiss German) would follow a chain like de-CHdeen. The system checks each step and serves the first translation it finds. If none of the locales in the chain have the key, most frameworks either display the raw key or an empty string, depending on configuration.

⁉️ Why fallback chains need to be implemented from localization teams #️⃣

Without a fallback chain, shipping a new language requires 100% translation coverage before any user can see content in that locale. With one properly configured, teams can publish partially translated interfaces where users see their preferred language for completed strings and a readable alternative for the rest. This makes incremental localization practical and prevents users from encountering broken UI, empty fields, or raw translation keys where text should be.

The logic works in both directions: it protects users during active translation work, and it keeps regional variants lean. Rather than duplicating every string in fr-CA just to differ on a handful of terms, teams can store only what differs and let the rest fall back to fr.

🔗 Fallback chain best practices #️⃣

  • Start specific, end generic. Begin with regional variants and move through parent languages to a widely understood base language.
  • Match linguistic proximity. pt-BR falling back to pt-PT before es makes more sense than jumping directly to English. Configure chains based on how related the languages actually are.
  • Avoid circular dependencies. Never create a loop where locales reference each other (fr-FRfr-CHfr-FR). Most frameworks will either throw an error or hang indefinitely.
  • Keep chains short. Two to three levels is the practical limit. Deeper chains are harder to reason about and debug.
  • Document the logic. Make fallback configuration visible to translators and content teams so they understand what users actually see when translations are incomplete.
  • Test fallback behavior. Verify that missing translations trigger the correct fallback sequence and that the resulting text does not break UI layouts, especially for languages with different text lengths.

⚠️ A common pitfall: null and empty strings #️⃣

Fallback chains only trigger when a translation key is entirely absent. If a key exists but is set to null or an empty string "", most frameworks treat that as a valid value and return it rather than falling back. This means a translator who saves a blank translation can silently break the fallback behavior. Teams relying on fallbacks should validate that incomplete translations are actually missing rather than empty.

⬜️ Namespace fallback #️⃣

Fallback logic also applies to namespaces, not just locales. If a key is missing from the active namespace, frameworks like i18next can fall back to a secondary namespace, such as a shared common namespace, before giving up. This is configured separately from locale fallback but follows the same sequential logic.

How Localazy supports fallback workflows #️⃣

Localazy’s coverage tracking and release controls help teams see exactly which locales are incomplete before publishing. This reduces reliance on fallback chains as a permanent workaround and makes it easier to plan translation work toward full coverage per locale.

Curious about software localization beyond the terminology?

⚡ Manage your translations with Localazy! 🌍