---
title: "Fall back to the closest supported locale · Agent Wranglers"
url: https://agentwranglers.se/playbook/localization/locales-and-preferences/locale-fallback
id: LOC-23
level: Recommended
updated: 2026-10-22
tokens: 1064
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Fall back to the closest supported locale

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [Locales and preferences](https://agentwranglers.se/playbook/localization/locales-and-preferences.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers.md). Updated 2026-10-22.

- ID: LOC-23
- Level: Recommended
- Chapter: [Locales and preferences](https://agentwranglers.se/playbook/localization/locales-and-preferences.md)
- Rule: Choose each request's locale from the user's saved choice first, then `Accept-Language`, then the default. Match against the supported list by removing subtags from the end and following CLDR parent locales.
- Check: A unit test resolves `pt-AO`, `zh-Hant-TW`, `de-CH` and `xx` against the supported list. Each gets the expected locale, and `xx` gets the default.
- How: RFC 4647 lookup turns `zh-Hant-TW` into `zh-Hant`, then `zh`, until one matches. CLDR adds parent locales that plain truncation misses, such as `es-MX` falling back to `es-419` before `es`. Use a matcher from your i18n library, such as `@formatjs/intl-localematcher` or Babel's `negotiate_locale`, instead of comparing strings. Treat `Accept-Language` as a first guess only, because it names a language, not where someone lives. Save an explicit choice from [Let people pick their language](https://agentwranglers.se/playbook/localization/locales-and-preferences/language-switcher.md) and let it win.

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### JavaScript example

```js
import { match } from '@formatjs/intl-localematcher';
const SUPPORTED = ['en', 'sv', 'pt-PT', 'zh-Hant'];
const DEFAULT_LOCALE = 'en';
export const resolveLocale = (saved, acceptLanguages) =>
  match(saved ? [saved] : acceptLanguages, SUPPORTED, DEFAULT_LOCALE);
resolveLocale(null, ['zh-Hant-TW', 'en']); // "zh-Hant"
```

### Python example

```python
from babel import negotiate_locale

SUPPORTED = ["en", "sv", "pt_PT", "zh_Hant"]
DEFAULT_LOCALE = "en"

def resolve_locale(saved: str | None, accept_languages: list[str]) -> str:
    wanted = [saved] if saved else accept_languages
    return negotiate_locale([tag.replace("-", "_") for tag in wanted], SUPPORTED) or DEFAULT_LOCALE
```

## Sources

- [RFC 4647 (Matching of Language Tags, section 3.4 Lookup)](https://www.rfc-editor.org/rfc/rfc4647#section-3.4)
- [Unicode LDML Part 1 (Locale inheritance and parent locales)](https://www.unicode.org/reports/tr35/tr35.html)
- [W3C Accept-Language used for locale setting](https://www.w3.org/International/questions/qa-accept-lang-locales)

## Related rules

- LOC-8 [Let people pick their language](https://agentwranglers.se/playbook/localization/locales-and-preferences/language-switcher.md) in Localization
- LOC-25 [Ship a default text for every message](https://agentwranglers.se/playbook/localization/messages-and-translation/default-messages.md) in Localization
- LOC-33 [Answer human-readable text in the language the client asked for](https://agentwranglers.se/playbook/localization/apis-and-data/response-language.md) in Localization
- LOC-35 [Store translated content per record and language](https://agentwranglers.se/playbook/localization/apis-and-data/translated-content-storage.md) in Localization

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which requires credit with a link. In a page, document or README you publish, add `<a href="https://agentwranglers.se/playbook/localization/locales-and-preferences/locale-fallback">Agent Wranglers localization playbook</a>`. In code you write, add a comment next to it with the same link.

- Previous: [Store language and time zone as two separate settings](https://agentwranglers.se/playbook/localization/locales-and-preferences/locale-and-time-zone-preferences.md)
- Next: [Let people pick their language](https://agentwranglers.se/playbook/localization/locales-and-preferences/language-switcher.md)
- [Locales and preferences](https://agentwranglers.se/playbook/localization/locales-and-preferences.md)