> ## Documentation Index
> Fetch the complete documentation index at: https://developers.phrase.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Language fallbacks

> How OTA decides which translation file to serve when the requested language isn't available

A distribution's **Fallback languages** settings control what happens when a device requests a language that isn't available in the release it receives. This page explains what each setting does and walks through how they interact, including across releases.

## The three settings

<Note>
  **Use language fallback** and the two settings below it look related, but they solve different problems. The first affects the *content* of a translation file; the other two affect *which* file gets served.
</Note>

### Use language fallback

When enabled, any translation keys missing from a language are filled in with the corresponding text from that language's fallback language (as configured in your project's language settings) at the time the release is published. This changes what's *inside* a given language's file — it has no effect on which language file a device is served when the exact language it asked for isn't part of the release at all.

### Fallback languages exclude regions (recommended)

If a device requests a regional variant (e.g. `de-DE`) that isn't part of the release, but the base language (e.g. `de`) is, OTA serves the base language instead.

> `de-DE` not found? Then `de` is used instead.

This only helps when the *same* release contains the base language. It does nothing if the release has neither the regional variant nor the base language.

### Fallback languages use the default locale (recommended)

If the requested language isn't part of the release at all — and the regional fallback above didn't resolve it either — OTA serves the project's default locale instead, regardless of how unrelated the two languages are.

> `fr` not found? Then the project's default locale, `en-US`, is used instead.

## How OTA picks a language, step by step

For a given device request, OTA looks at releases from **newest to oldest**, stopping at the first release whose app version range matches the device. Within that release, it tries, in order:

1. **Exact match** — is the requested language part of this release? If so, serve it.
2. **Region fallback** (if enabled) — is the base language (without the region) part of this release? If so, serve it.
3. **Default locale fallback** (if enabled) — is the project's default locale part of this release? If so, serve it.

If none of these three steps finds anything in that release, OTA doesn't give up — it moves on to the **next older release** whose app version range matches, and repeats the same three steps there. This continues until a language resolves, or there are no more matching releases to check (at which point the request fails with a "language not found" response).

<Tip>
  Because fallback resolution always happens *within* a release before OTA ever considers an older one, enabling the default-locale fallback can cause a device to receive a fallback language from the newest release instead of the exact language it would have gotten from an older release. See the example below.
</Tip>

## Examples

### Region fallback within a release

Suppose a distribution has published a single release containing English, French, and German (`de`, no regional variant) — no Austrian German (`de-AT`). Default locale: English. A device configured for Austrian German requests `de-AT`:

| Exclude regions | What the device receives                                                                        | Why                                                                                                                                  |
| --------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| Off             | **English** (if default-locale fallback is on) or a "language not found" response (if it's off) | `de-AT` isn't in the release, and OTA has no way to drop the region on its own.                                                      |
| On              | **German** (`de`)                                                                               | OTA drops the region from `de-AT`, finds `de` in the same release, and serves it — without ever needing the default-locale fallback. |

This is the setting's main use case: a release rarely contains every regional variant of a language, but it often contains the base language, so dropping the region first avoids falling back to an unrelated default locale unnecessarily.

### Fallback across releases (default locale)

Suppose a distribution has published two releases, both covering the app version the device is running:

* **Release 1** (older): contains English and German. Default locale: English.
* **Release 2** (newer): contains English only. Default locale: English.

A device requests **German**. What it receives depends on the fallback settings on the distribution at the time Release 2 was published:

| Exclude regions | Use default locale | What the device receives    | Why                                                                                                                                              |
| --------------- | ------------------ | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| Off             | Off                | **German**, from Release 1  | Release 2 has no German and no fallback configured, so OTA moves on to Release 1, which has an exact match.                                      |
| On              | Off                | **German**, from Release 1  | The region fallback can't help here (the request has no region to drop, and Release 2 has no German at all), so OTA still moves on to Release 1. |
| Off             | On                 | **English**, from Release 2 | The default-locale fallback resolves inside Release 2 using English, so OTA stops there — Release 1 is never checked.                            |
| On              | On                 | **English**, from Release 2 | Same as above; the region fallback is a no-op in this case, but the default-locale fallback still resolves in Release 2.                         |

The takeaway: enabling **use default locale** trades "may return the wrong language from a newer release" for "always returns *some* usable language rather than an error." Whether that trade-off is desirable depends on whether you'd rather your app show a slightly older release in the requested language, or the newest release in a fallback language.

<Note>
  Fallback settings only take effect on releases published after you change them. If you update a distribution's fallback settings, publish a new release for the change to apply.
</Note>

Fallbacks do not apply to linked keys.