Localization - Primer

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

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.

Web
Android
iOS

Pass a locale to the SDK using the options property. See SDK Options for details.Web supports all locales marked All in the table above. The remaining locales (marked iOS, Android) are coming soon.

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:

private let primerSettings = PrimerSettings(
  localeData: PrimerLocaleData(languageCode: "fr", regionCode: "FR")
)

Locale Fallback Behavior

Web
Android
iOS

Primer Checkout Web uses BCP 47 language tags and implements automatic fallback for regional variants.

How it works

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

Usage

Check SDK options guide to learn how to pass a locale property.

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:

// 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.

The iOS SDK follows the standard iOS locale resolution. The device’s language setting is used automatically.

How it works

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

Setting an explicit locale

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.

Checkout

​Supported Locales

​Locale Fallback Behavior

​How it works

​Usage

​Currency formatting

​RTL support

​How it works

​Setting an explicit locale

​RTL support

Supported Locales

Locale Fallback Behavior

How it works

Usage

Currency formatting

RTL support

How it works

Setting an explicit locale

RTL support