Checkout Language Management

The checkout interface language is configured when initializing the SDK via the locale object in window.DNAPayments.configure(...). Three modes are supported: explicit locale, automatic detection from the user's browser, and a combined mode with fallback.

The locale object

All fields are optional. Pass any combination of them to control how the checkout language is resolved.

Field	Type	Required	Default	Description
targetLocale	string	No	—	Forces the checkout to a specific locale. Highest priority — when set, both detectLocale and defaultLocale are ignored.
detectLocale	boolean	No	false	If true, the SDK reads the user's browser language and matches it to the closest supported locale. Ignored when targetLocale is set.
defaultLocale	string	No	en_GB	Locale used when targetLocale is not set and auto-detection cannot match a supported language.

targetLocale and defaultLocale accept any of the supported locale codes.

Supported locales

Code	Language	Region
en_GB	English	United Kingdom
de_DE	German	Germany
es_ES	Spanish	Spain
pt_PT	Portuguese	Portugal
is_IS	Icelandic	Iceland

If no locale is specified, en_GB is used.

How to set the language

1. Explicit locale (recommended when the audience is known)

window.DNAPayments.configure({
    locale: {
        targetLocale: 'de_DE'
    }
    // ... other parameters
})

targetLocale has the highest priority and always wins over any other settings.

2. Automatic detection of the user's language

Enabled with detectLocale: true. The SDK reads the language from the browser settings and matches it to the closest supported locale.

window.DNAPayments.configure({
    locale: {
        detectLocale: true
    }
})

If the browser language is not in the supported list, en_GB is used.

3. Automatic detection with a custom fallback

If you want a different fallback than en_GB when detection cannot match a supported language (for example, on a German-focused site):

window.DNAPayments.configure({
    locale: {
        detectLocale: true,
        defaultLocale: 'de_DE'
    }
})

Resolution priority

The locale is resolved in the following order — the first match wins:

1. locale.targetLocale — explicitly set locale.
2. Result of auto-detection (if detectLocale: true).
3. locale.defaultLocale — your fallback.
4. en_GB — global fallback.

If targetLocale is set, the detectLocale flag is ignored.