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

# Checkout Localization

> Show checkout in the buyer's own language to lift conversion worldwide

A buyer who sees the price, fields, and call-to-action in their own language is far more likely to complete the purchase. Macropay localization translates the hosted checkout automatically, so a customer in Lyon sees French and a customer in São Paulo sees Brazilian Portuguese — no extra code on your side.

Because Macropay is the **merchant of record**, the same checkout already handles global sales tax and VAT collection and shows the correct tax line for the buyer's country. Localization rounds that out: the entire purchase moment reads as native, from the tax label to the pay button.

<Note>
  Checkout localization is in **beta**. Turn on the feature flag for your
  organization to enable it.
</Note>

## Automatic language detection

Once the flag is on, the checkout inspects the buyer's browser language (the `Accept-Language` header) and renders in the closest supported match. Translations cover the standard checkout surface — field labels, placeholders, helper text, and descriptions — with English as the fallback when no match is found.

There is nothing to configure per checkout. A buyer whose browser is set to German sees German automatically.

## Forcing a specific language

Automatic detection is the default, but you can pin the language yourself in two ways. An explicit `locale` always wins over the browser preference.

### Via the Checkout Sessions API

Pass `locale` when you create a checkout session. This is the right approach when you already know the customer's language — for example, you store it in your own user profile.

```bash theme={null}
curl -X POST https://api.macropay.ai/v1/checkouts/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "products": ["<product_id>"],
    "locale": "es"
  }'
```

### Via the checkout URL

Append `?locale=` to any checkout link. Handy for marketing pages where one localized landing page links straight to a matching checkout:

```text theme={null}
https://buy.macropay.ai/<checkout_id>?locale=pt
```

Both overrides take precedence over the browser's detected language.

## Supported languages

| Language              | Code    |
| --------------------- | ------- |
| English (default)     | `en`    |
| Dutch                 | `nl`    |
| Spanish               | `es`    |
| French                | `fr`    |
| Swedish               | `sv`    |
| German                | `de`    |
| Hungarian             | `hu`    |
| Italian               | `it`    |
| Portuguese (Brazil)   | `pt`    |
| Portuguese (Portugal) | `pt-PT` |

**Coming soon:** Korean (`kr`).

<Tip>
  Want to help review translations for a language we're adding? We welcome
  native-speaker reviewers — reach out at
  [translations@macropay.ai](mailto:translations@macropay.ai).
</Tip>

## What's localized today

During beta, translation is scoped to the **checkout page** itself. These surfaces still render in English for now:

| Surface                                        | Beta status |
| ---------------------------------------------- | ----------- |
| Checkout fields, labels, descriptions          | Localized   |
| Validation / error messages                    | English     |
| Transactional emails (receipts, confirmations) | English     |
| Customer portal                                | English     |

There is also **no on-page language switcher** — the language is resolved automatically from the browser, or set explicitly through the API `locale` parameter or the `?locale` query string.

## Tell us what to translate next

Localization grows fastest with input from teams shipping to real buyers:

* Open an issue on [GitHub](mailto:support@macropay.ai)
* Email the i18n team at [i18n@macropay.ai](mailto:i18n@macropay.ai)