Add localization to Flow for mobile
Beta

Last updated: April 23, 2025

By default, the language displayed on Flow is derived from the locale set in the payment-session request.

Alternatively, you can use the locale configuration option to manually set the language in the configuration. For example:


1val configuration = CheckoutComponentConfiguration(
2   context = context,
3   paymentSession = paymentSession,
4   publicKey = publicKey,
5   environment = environment,
6   locale = Locale.En
7)


1let configuration = try await CheckoutComponents.Configuration(
2   paymentSession: paymentSession,
3   publicKey: publicKey,
4   environment: environment,
5   appearance: appearance,
6   locale: "en-GB",
7   callbacks: callbacks
8)

The following left-to-right (LTR) and right-to-left (RTL) languages are supported:

Language	Android locale	Language type
Arabic	`Locale.Ar`	`RTL`
Chinese (China)	`Locale.Zh`	`LTR`
Chinese (Hong Kong)	`Locale.ZhHk`	`LTR`
Chinese (Taiwan)	`Locale.ZhTw`	`LTR`
Danish	`Locale.Da`	`LTR`
Dutch (Netherlands)	`Locale.Nl`	`LTR`
English (United Kingdom)	`Locale.En`	`LTR`
Filipino	`Locale.Fil`	`LTR`
Finnish	`Locale.Fi`	`LTR`
French	`Locale.Fr`	`LTR`
German	`Locale.De`	`LTR`
Greek	`Locale.El`	`LTR`
Hindi	`Locale.Hi`	`LTR`
Indonesian	`Locale.Id`	`LTR`
Italian	`Locale.It`	`LTR`
Japanese	`Locale.Ja`	`LTR`
Malay	`Locale.Ms`	`LTR`
Norwegian Bokmål	`Locale.Nb`	`LTR`
Portuguese	`Locale.Pt`	`LTR`
Spanish	`Locale.Es`	`LTR`
Swedish	`Locale.Sv`	`LTR`
Thai	`Locale.Th`	`LTR`
Vietnamese	`Locale.Vi`	`LTR`

Language	iOS locale	Language type
Arabic	`ar`	`RTL`
Chinese (China)	`zh-CN`	`LTR`
Chinese (Hong Kong)	`zh-HK`	`LTR`
Chinese (Taiwan)	`zh-TW`	`LTR`
Danish	`da-DK`	`LTR`
Dutch (Netherlands)	`nl-NL`	`LTR`
English (United Kingdom)	`en-GB`	`LTR`
Filipino	`fil-PH`	`LTR`
Finnish	`fi-FI`	`LTR`
French	`fr-FR`	`LTR`
German	`de-DE`	`LTR`
Greek	`el`	`LTR`
Hindi	`hi-IN`	`LTR`
Indonesian	`id-ID`	`LTR`
Italian	`it-IT`	`LTR`
Japanese	`ja-JP`	`LTR`
Malay	`ms-MY`	`LTR`
Norwegian Bokmål	`nb-NO`	`LTR`
Portuguese	`pt-PT`	`LTR`
Spanish	`es-ES`	`LTR`
Swedish	`sv-SE`	`LTR`
Thai	`th-TH`	`LTR`
Vietnamese	`vi-VN`	`LTR`

You can customize the default text translation for a specific language by providing your own strings.

Create a translations object and specify the locale for which you want to provide custom translations. Within the locale object, include the translation keys you want to customize, along with their values. For example:


1val translations = mapOf(
2   Locale.En to mapOf(
3       ComponentTranslationKey.FormRequired to "Please provide this field",
4       ComponentTranslationKey.PayButtonPay to "Pay Now",
5       ComponentTranslationKey.PaymentDeclinedTryAgain to "Payment failed, please try again",
6   )
7)


1let translations = [
2    "en-GB": [
3      .formRequired: "Please provide this field",
4      .payButtonPay: “Pay Now”,
5      .paymentDeclinedTryAgain: “Payment failed, please try again”
6    ]
7  ]

Pass the translations object when you create the instance of configuration.


1val configuration = CheckoutComponentConfiguration(
2   context = context,
3   paymentSession = paymentSession,
4   publicKey = publicKey,
5   environment = environment,
6   translations =translations,
7)


1let configuration = try await CheckoutComponents.Configuration(
2   paymentSession: paymentSession,
3   publicKey: publicKey,
4   environment: environment,
5   appearance: appearance,
6   locale: "en-US",
7   translations: translations,
8   callbacks: callbacks
9)

You can customize the following default text:

Translation key	Default text	Description
`AddressAddressLine1`	Address line 1	The label for the first line of the address.
`AddressAddressLine2`	Address line 2	The label for the second line of the address.
`AddressBillingAdd`	Add billing address	The label for the button to add a billing address.
`AddressCity`	Town or City	The label for the city input field.
`AddressCountry`	Country	The label for the country selection field.
`AddressCountrySelect`	Select Country	The title for the country selection screen.
`AddressEditAddress`	Edit address	The button text for editing an existing address.
`AddressState`	State or province	The label for the state/province input field.
`AddressZip`	ZIP or postal code	The label for the ZIP/postal code input field.
`Card`	Card	The label for the card option.
`CardAddressUseShippingAsBilling`	Use shipping address as billing address	The label for the checkbox to use the shipping address as the billing address.
`CardHolderName`	Cardholder name	The label for the cardholder name input.
`CardNumber`	Card number	The card number label for the card number input.
`CardNumberInvalid`	Card number is incomplete	The error message displayed when the card number is incomplete.
`CardNumberNotSupported`	`%s` not supported	The error message displayed when the card number is from an unsupported card scheme.
`CardExpiryDate`	Expiry date	The label for the card expiry date input.
`CardExpiryDateInvalid`	Expiry date is in the past	The error message displayed when the card expiry date is invalid.
`CardExpiryDateIncomplete`	Expiry date is incomplete	The error message displayed when the card expiry date is incomplete.
`CardExpiryDatePlaceholderMonth`	MM	The message describing the format for the card expiry month input.
`CardExpiryDatePlaceholderYear`	YY	The message describing the format for the card expiry year input.
`CardSecurityCode`	Security code	The security code label for the card security code (CVV) input.
`CardSecurityCodeInvalid`	Security code is incomplete	The error message displayed when the security code (CVV) is incomplete.
`CardSecurityCodePlaceholder`	CVV	The message describing the format for the card security code input.
`FormAddAddress`	Add address	The button text for adding an address.
`FormEmailFormatInvalid`	Incorrect email format	The validation message when an email address is in an invalid format.
`FormExceedCharacterLimit`	Exceeds {VALUE} character limit	The validation message when input exceeds the maximum character limit, where {VALUE} is replaced with the actual limit number.
`FormFirstName`	First name	The label for the first name input field.
`FormInsufficientCharacters`	Insufficient characters	The validation message when input doesn't meet minimum character requirements.
`FormLastName`	Last name	The label for the last name input field.
`FormNoMatchesFound`	No matches found	The message displayed when a search returns no results.
`FormOptional`	Optional	The label indicating that a field is not required.
`FormRequired`	This field is required	The validation message displayed when the customer leaves a required field blank.
`FormSearch`	Search	The placeholder text for search inputs.
`FormTrySearchingWithAnotherTerm`	Try searching with another term.	The suggestion shown when no search results are found.
`PayButtonConfirm`	Confirm	The label for the Confirm button.
`PayButtonPay`	Pay	The call to action displayed on the pay button.
`PayButtonPaymentComplete`	Payment complete	The message displayed when the payment is completed.
`PayButtonPaymentProcessing`	Payment processing	The message displayed while the payment is processing.
`PaymentDeclinedInvalidCustomerData`	Incorrect details – try again or use another payment method	The error message displayed when the customer provides invalid payment details.
`PaymentDeclinedInvalidPaymentSessionData`	Try another payment method	The error message displayed when the `PaymentSession` data provided is invalid for the chosen payment method. This exists to cover edge cases and should not occur.
`PaymentDeclinedMerchantMisconfiguration`	Payment declined – try another payment method	The error message displayed when your integration is misconfigured for the chosen payment method.
`PaymentDeclinedNotEnoughFunds`	Not enough funds – try another payment method	The error message displayed when the customer does not have sufficient funds to complete the transaction with their chosen payment method.
`PaymentDeclinedTryAgain`	Payment declined – try again or use another payment method	The fallback message displayed when the chosen payment method declines the transaction.

Translation key	Default text	Description
`address`	Address	The general label for an address.
`addressAddressLine1`	Address line 1	The label for the first line of the address.
`addressAddressLine2`	Address line 2	The label for the second line of the address.
`addressBillingAdd`	Add billing address	The label for the button to add a billing address.
`addressCity`	Town or City	The label for the city input field.
`addressCountry`	Country	The label for the country selection field.
`addressCountrySelect`	Select Country	The title for the country selection screen.
`addressEditAddress`	Edit address	The button text for editing an existing address.
`addressSelectCountryCode`	Select country code	The label for selecting a country calling code for phone numbers.
`addressState`	State or province	The label for the state/province input field.
`addressZip`	ZIP or postal code	The label for the ZIP/postal code input field.
`billingAddress`	Billing Address	The label for the billing address section.
`card`	Card	The label for the card option.
`cardAddressUseShippingAsBilling`	Use shipping address as billing address	The label for the checkbox to use the shipping address as the billing address.
`cardHolderName`	CardHolder name	The label for the cardholder name input.
`cardNumber`	Card number	The card number label for the card number input.
`cardNumberInvalid`	Card number is incomplete	The error message displayed when the card number is incomplete.
`cardNumberNotSupported`	`%@` not supported	The error message displayed when the card number is from an unsupported card scheme.
`cardExpiryDate`	Expiry date	The label for the card expiry date input.
`cardExpiryDateInvalid`	Expiry date is in the past	The error message displayed when the card expiry date is invalid.
`cardExpiryDateIncomplete`	Expiry date is incomplete	The error message displayed when the card expiry date is incomplete.
`cardExpiryDatePlaceholderMonth`	MM	The message describing the format for the card expiry month input.
`cardExpiryDatePlaceholderYear`	YY	The message describing the format for the card expiry year input.
`cardSecurityCode`	Security code	The security code label for the card security code (CVV) input.
`cardSecurityCodeInvalid`	Security code is incomplete	The error message displayed when the security code (CVV) is incomplete.
`cardSecurityCodePlaceholder`	CVV	The message describing the format for the card security code input.
`confirm`	Confirm	The label for the confirm button.
`email`	Email	The label for the email input field.
`formAddAddress`	Add Address	The button text for adding an address.
`formEmailFormatInvalid`	Incorrect email format	The validation message when an email address is in an invalid format.
`formFirstName`	First name	The label for the first name input field.
`formInsufficientCharacters`	Insufficient characters	The validation message when input doesn't meet minimum character requirements.
`formLastName`	Last name	The label for the last name input field.
`formNoMatchesFound`	No matches found	The message displayed when a search returns no results.
`formOptional`	Optional	The label indicating that a field is not required.
`formRequired`	This field is required	The validation message displayed when the customer leaves a required field blank.
`formSearch`	Search	The placeholder text for search inputs.
`formTrySearchingWithAnotherTerm`	Try searching with another term.	The suggestion shown when no search results are found.
`payButtonPay`	Pay	The call to action displayed on the pay button.
`payButtonPaymentComplete`	Payment complete	The message displayed when the payment is completed.
`payButtonPaymentProcessing`	Payment processing	The message displayed while the payment is processing.
`paymentDeclinedInvalidCustomerData`	Incorrect details – try again or use another payment method	The error message displayed when the customer provides invalid payment details.
`paymentDeclinedInvalidPaymentSessionData`	Try another payment method	The error message displayed when the `PaymentSession` data provided is invalid for the chosen payment method. This exists to cover edge cases and should not occur.
`paymentDeclinedMerchantMisconfiguration`	Payment declined – try another payment method	The error message displayed when your integration is misconfigured for the chosen payment method.
`paymentDeclinedNotEnoughFunds`	Not enough funds – try another payment method	The error message displayed when the customer does not have sufficient funds to complete the transaction with the chosen payment method.
`paymentDeclinedTryAgain`	Payment declined – try again or use another payment method	The fallback message displayed when the chosen payment method declines the transaction.
`phoneNumber`	Phone number	The label for the phone number input field.

To add support for locales and languages not natively supported by Flow for mobile, provide the locale as an object of key-value pairs within the same translations object you used for custom translations. For example, to add support for US English (en-US):


1val translations = mapOf(
2   Locale.Customized(“en-US”) to mapOf(
3       ComponentTranslationKey.PayButtonPay to "Tap to Pay",
4   )
5)
6
7val configuration = CheckoutComponentConfiguration(
8   context = context,
9   paymentSession = paymentSession,
10   publicKey = publicKey,
11   environment = environment,
12   locale = Locale.Customized(“en-US”),
13   translations = translations
14)


1let translations = [
2    "en-US": [
3      .payButtonPay: "Tap to Pay"
4    ]
5  ]
6
7
8 let configuration = try await CheckoutComponents.Configuration(
9   paymentSession: paymentSession,
10   publicKey: publicKey,
11   environment: environment,
12   appearance: appearance,
13   locale: "en-US",
14   translations: translations,
15   callbacks: callbacks
16 )

Information

If you are missing a translation for the locale you provide, Flow will attempt to fall back to the language of the specified locale. If the locale language is not supported, Flow will fall back to English.

Flow library reference

See the configuration options and error handling steps for Flow for mobile.

Add localization to Flow for mobile
Beta

Supported languages

Add custom translations

Add support for additional languages

Information

Next steps

Flow library reference