# `Locale`

Language code type used to control the display language of the Revolut Checkout widget UI. The SDK supports 22 languages with automatic detection based on browser settings.

## Type signature

```typescript
type Locale =
  | 'en'
  | 'en-US'
  | 'nl'
  | 'fr'
  | 'de'
  | 'cs'
  | 'it'
  | 'lt'
  | 'pl'
  | 'pt'
  | 'es'
  | 'hu'
  | 'sk'
  | 'ja'
  | 'sv'
  | 'bg'
  | 'ro'
  | 'ru'
  | 'el'
  | 'hr'
  | 'tr'
```

## Supported languages

| Code    | Language     | Native name  |
| ------- | ------------ | ------------ |
| `en`    | English      | English      |
| `en-US` | English (US) | English (US) |
| `nl`    | Dutch        | Nederlands   |
| `fr`    | French       | Français     |
| `de`    | German       | Deutsch      |
| `cs`    | Czech        | Čeština      |
| `it`    | Italian      | Italiano     |
| `lt`    | Lithuanian   | Lietuvių     |
| `pl`    | Polish       | Polski       |
| `pt`    | Portuguese   | Português    |
| `es`    | Spanish      | Español      |
| `hu`    | Hungarian    | Magyar       |
| `sk`    | Slovak       | Slovenčina   |
| `ja`    | Japanese     | 日本語          |
| `sv`    | Swedish      | Svenska      |
| `bg`    | Bulgarian    | Български    |
| `ro`    | Romanian     | Română       |
| `ru`    | Russian      | Русский      |
| `el`    | Greek        | Ελληνικά     |
| `hr`    | Croatian     | Hrvatski     |
| `tr`    | Turkish      | Türkçe       |

## Usage

### Automatic locale detection

By default, the SDK detects the user's browser language automatically:

```typescript
import RevolutCheckout from '@revolut/checkout'

// Auto-detect browser locale
const { destroy } = await RevolutCheckout.embeddedCheckout({
  publicToken: 'pk_...',
  environment: 'prod',
  locale: 'auto', // Default value
  // ... other options
})
```

### Explicit locale setting

Set a specific language for all users:

```typescript
import RevolutCheckout from '@revolut/checkout'

// Force French locale
const { destroy } = await RevolutCheckout.embeddedCheckout({
  publicToken: 'pk_...',
  environment: 'prod',
  locale: 'fr',
  // ... other options
})
```

### Dynamic locale selection

Allow users to choose their preferred language:

```typescript
import RevolutCheckout from '@revolut/checkout'
import type { Locale } from '@revolut/checkout'

const userSelectedLanguage: Locale = 'es' // From language picker

const { destroy } = await RevolutCheckout.embeddedCheckout({
  publicToken: 'pk_...',
  environment: 'prod',
  locale: userSelectedLanguage,
  // ... other options
})
```

### With token-based initialisation

The [`setDefaultLocale()`](/docs/sdks/merchant-web-sdk/initialisation/token-based#setdefaultlocale) method allows changing the widget language after initialisation:

```typescript
import RevolutCheckout from '@revolut/checkout'

const instance = await RevolutCheckout(orderToken, 'prod')

// Set default locale for the instance
instance.setDefaultLocale('de')

// Open card popup with German locale
instance.payWithPopup({
  locale: 'de',
  onSuccess: () => console.log('Payment successful'),
})
```

:::info
For more details, see: [Token-based initialisation](/docs/sdks/merchant-web-sdk/initialisation/token-based#setdefaultlocale)
:::

### With payments module

The [`setDefaultLocale()`](/docs/sdks/merchant-web-sdk/initialisation/payments-module#setdefaultlocale) method allows changing the widget language after initialisation:

```typescript
import RevolutCheckout from '@revolut/checkout'

const paymentsModule = await RevolutCheckout.payments({
  publicToken: 'pk_...',
  mode: 'prod',
  locale: 'ja', // Japanese
})

// Update locale dynamically
paymentsModule.setDefaultLocale('sv') // Switch to Swedish
```

For more details, see: [Payments module initialisation](/docs/sdks/merchant-web-sdk/initialisation/payments-module#setdefaultlocale)

### With upsell module

The [`setDefaultLocale()`](/docs/sdks/merchant-web-sdk/initialisation/upsell-module#setdefaultlocale) method allows changing the widget language after initialisation:

```typescript
import RevolutCheckout from '@revolut/checkout'

const upsellModule = await RevolutCheckout.upsell({
  publicToken: 'pk_...',
  mode: 'prod',
  locale: 'ja', // Japanese
})

// Update locale dynamically
upsellModule.setDefaultLocale('sv') // Switch to Swedish
```

:::info
For more details, see: [Upsell module initialisation](/docs/sdks/merchant-web-sdk/initialisation/upsell-module#setdefaultlocale)
:::

## Fallback behaviour

If a locale is not supported or invalid:

- The SDK falls back to `'en'` (English)
- No error is thrown
- The widget continues to function normally

```typescript
// Invalid locale - falls back to English
const { destroy } = await RevolutCheckout.embeddedCheckout({
  locale: 'xyz' as any, // Invalid, will use 'en'
  // ... other options
})
```

## Best practices

### Let users choose

Provide a language selector in your checkout:

```typescript
const languages: Array<{ code: Locale; name: string }> = [
  { code: 'en', name: 'English' },
  { code: 'fr', name: 'Français' },
  { code: 'de', name: 'Deutsch' },
  { code: 'es', name: 'Español' },
  // ... more languages
]

function LanguageSelector({ onChange }: { onChange: (locale: Locale) => void }) {
  return (
    <select onChange={(e) => onChange(e.target.value as Locale)}>
      {languages.map(({ code, name }) => (
        <option key={code} value={code}>
          {name}
        </option>
      ))}
    </select>
  )
}
```

### Match your site locale

Ensure consistency between your site and the widget:

```typescript
import { useLocale } from './i18n' // Your i18n solution
import type { Locale } from '@revolut/checkout'

// Map your locale to Revolut Checkout locale
function getCheckoutLocale(siteLocale: string): Locale | 'auto' {
  const localeMap: Record<string, Locale> = {
    'en-GB': 'en',
    'en-US': 'en-US',
    'fr-FR': 'fr',
    'de-DE': 'de',
    // ... more mappings
  }

  return localeMap[siteLocale] || 'auto'
}

const checkoutLocale = getCheckoutLocale(useLocale())
```

### Store user preference

Remember the user's language choice:

```typescript
import type { Locale } from '@revolut/checkout'

function getPreferredLocale(): Locale | 'auto' {
  const stored = localStorage.getItem('preferredLocale')
  return (stored as Locale) || 'auto'
}

function setPreferredLocale(locale: Locale): void {
  localStorage.setItem('preferredLocale', locale)
}

// Use stored preference
const { destroy } = await RevolutCheckout.embeddedCheckout({
  locale: getPreferredLocale(),
  // ... other options
})
```

## See also

- [Direct initialisation](/docs/sdks/merchant-web-sdk/initialisation/direct)
- [Token-based initialisation](/docs/sdks/merchant-web-sdk/initialisation/token-based)
- [Payments module initialisation](/docs/sdks/merchant-web-sdk/initialisation/payments-module)
- [Upsell module initialisation](/docs/sdks/merchant-web-sdk/initialisation/upsell-module)