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

# Localization

> Locales supported by Primer Checkout.

Primer Checkout supports multiple languages and automatically adapts the checkout UI to the shopper's locale.

## Supported Locales

Primer Checkout supports the following locales. If a specific regional variant is not supported, it falls back gracefully to the closest available language.

| Locale  | Language              | Platforms    |
| ------- | --------------------- | ------------ |
| `ar`    | Arabic                | All          |
| `az`    | Azerbaijani           | iOS, Android |
| `bg`    | Bulgarian             | All          |
| `bs`    | Bosnian               | iOS, Android |
| `ca`    | Catalan               | All          |
| `cs`    | Czech                 | All          |
| `da`    | Danish                | All          |
| `de`    | German                | All          |
| `el`    | Greek                 | All          |
| `en`    | English               | All          |
| `es`    | Spanish               | All          |
| `es-AR` | Spanish (Argentina)   | All          |
| `es-MX` | Spanish (Mexico)      | All          |
| `et`    | Estonian              | All          |
| `fa`    | Persian               | iOS, Android |
| `fi`    | Finnish               | All          |
| `fil`   | Filipino              | iOS, Android |
| `fr`    | French                | All          |
| `he`    | Hebrew                | All          |
| `hi`    | Hindi                 | iOS, Android |
| `hr`    | Croatian              | All          |
| `hu`    | Hungarian             | All          |
| `hy`    | Armenian              | iOS, Android |
| `id`    | Indonesian            | All          |
| `it`    | Italian               | All          |
| `ja`    | Japanese              | All          |
| `ka`    | Georgian              | iOS, Android |
| `kk`    | Kazakh                | iOS, Android |
| `ko`    | Korean                | All          |
| `ku`    | Kurdish               | iOS, Android |
| `ky`    | Kyrgyz                | iOS, Android |
| `lt`    | Lithuanian            | All          |
| `lv`    | Latvian               | All          |
| `mk`    | Macedonian            | iOS, Android |
| `ms`    | Malay                 | All          |
| `nb`    | Norwegian Bokmal      | All          |
| `nl`    | Dutch                 | All          |
| `nl-BE` | Dutch (Belgium)       | iOS, Android |
| `pl`    | Polish                | All          |
| `pt`    | Portuguese            | All          |
| `pt-BR` | Portuguese (Brazil)   | All          |
| `ro`    | Romanian              | All          |
| `ru`    | Russian               | All          |
| `sk`    | Slovak                | All          |
| `sl`    | Slovenian             | All          |
| `sq`    | Albanian              | iOS, Android |
| `sr`    | Serbian               | All          |
| `sv`    | Swedish               | All          |
| `th`    | Thai                  | All          |
| `tr`    | Turkish               | All          |
| `uk`    | Ukrainian             | All          |
| `ur-PK` | Urdu (Pakistan)       | iOS, Android |
| `uz`    | Uzbek                 | iOS, Android |
| `vi`    | Vietnamese            | All          |
| `zh-CN` | Chinese (Simplified)  | All          |
| `zh-HK` | Chinese (Hong Kong)   | All          |
| `zh-TW` | Chinese (Traditional) | All          |

<Note>
  Locales marked **iOS, Android** are not yet available on Web. Regional variants automatically fall back to the base language — for example, `pl-PL` (Polish - Poland) will use `pl` (Polish) translations.
</Note>

<Tabs>
  <Tab title="Web">
    Pass a locale to the SDK using the `options` property. See [SDK Options](/checkout/primer-checkout/configuration/sdk-options) for details.

    Web supports all locales marked **All** in the table above. The remaining locales (marked **iOS, Android**) are coming soon.
  </Tab>

  <Tab title="Android">
    The SDK automatically adapts to the device's locale for field labels, error messages, button text, currency formatting, and date formatting. No additional configuration is required.

    Android supports all locales listed in the table above.
  </Tab>

  <Tab title="iOS">
    The SDK automatically adapts to the device's locale for field labels, error messages, button text, and currency formatting. No additional configuration is required.

    iOS supports all locales listed in the table above. To set an explicit locale, use `PrimerLocaleData` in `PrimerSettings`:

    ```swift theme={"dark"}
    private let primerSettings = PrimerSettings(
      localeData: PrimerLocaleData(languageCode: "fr", regionCode: "FR")
    )
    ```
  </Tab>
</Tabs>

## Locale Fallback Behavior

<Tabs>
  <Tab title="Web">
    Primer Checkout Web uses [BCP 47](https://www.rfc-editor.org/info/bcp47) language tags and implements automatic fallback for regional variants.

    ### How it works

    1. **Exact match**: The SDK first looks for an exact match (e.g., `pl-PL`)
    2. **Base language fallback**: If no exact match exists, it falls back to the base language (e.g., `pl`)
    3. **Default fallback**: If neither matches, it defaults to `en-GB`

    ### Usage

    Check [SDK options guide](/checkout/primer-checkout/configuration/sdk-options#2-options-object) to learn how to pass a locale property.
  </Tab>

  <Tab title="Android">
    The Android SDK follows the standard Android locale resolution. The device's system locale is used automatically, and Compose's built-in layout mirroring handles RTL languages.

    ### Currency formatting

    The SDK formats amounts using the currency code from your client session:

    ```kotlin theme={"dark"}
    // With USD client session
    checkout.formatAmount(1000) // "$10.00"

    // With EUR client session
    checkout.formatAmount(1000) // "10,00 EUR"

    // With JPY client session (no minor units)
    checkout.formatAmount(1000) // "JPY1,000"
    ```

    ### RTL support

    The SDK supports right-to-left (RTL) layouts automatically when the device locale is set to an RTL language. Compose's built-in layout mirroring handles the directional adjustments.
  </Tab>

  <Tab title="iOS">
    The iOS SDK follows the standard iOS locale resolution. The device's language setting is used automatically.

    ### How it works

    1. **Explicit locale**: If `PrimerLocaleData` is set in `PrimerSettings`, that locale is used
    2. **Device language**: Otherwise, the device's current language setting is used
    3. **Base language fallback**: If only the language matches (e.g., `en` for `en-AU`), the base language strings are used
    4. **Default fallback**: If no match is found, English (`en`) is used as the fallback

    ### Setting an explicit locale

    ```swift theme={"dark"}
    private let primerSettings = PrimerSettings(
      localeData: PrimerLocaleData(languageCode: "de", regionCode: "DE")
    )
    ```

    ### RTL support

    The SDK supports right-to-left (RTL) layouts automatically when the device locale is set to an RTL language such as Arabic (`ar`) or Hebrew (`he`). SwiftUI's built-in layout mirroring handles the directional adjustments.
  </Tab>
</Tabs>