# Localization (/guides/localization)

The strings Bitelio itself renders — the unsubscribe footer it appends to marketing emails, plus the hosted unsubscribe, subscribe, and preferences pages — can be served in your contacts' languages. What Bitelio never touches is your own template content: subjects and body copy are **not** auto-translated, and remain fully under your control.

## Setting the project default

Under **Settings → Project**, choose a default language. Contacts without a language of their own on record get this one.

## Overriding per contact

To give an individual recipient a different language, write a `locale` field into the contact's `data`:

```bash
curl -X POST https://bitelio-api.heltia.com/v1/track \
  -H "Authorization: Bearer pk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ada@example.com",
    "event": "signed_up",
    "data": { "locale": "fr" }
  }'
```

The value should be a [BCP 47](https://en.wikipedia.org/wiki/IETF_language_tag) / ISO 639 code from the supported list below. The field is also available as `{{locale}}` in template variables, so you can branch your own copy on it.

When a contact's `locale` isn't among the supported languages, the project default takes over; when neither is set, everything renders in English.

## Supported languages

| Code    | Language                         |
| ------- | -------------------------------- |
| `en`    | English                          |
| `nl`    | Dutch (Nederlands)               |
| `fr`    | French (Français)                |
| `de`    | German (Deutsch)                 |
| `es`    | Spanish (Español)                |
| `it`    | Italian (Italiano)               |
| `pt`    | Portuguese (Português)           |
| `pl`    | Polish (Polski)                  |
| `cs`    | Czech (Čeština)                  |
| `bg`    | Bulgarian (Български)            |
| `hi`    | Hindi (हिंदी)                    |
| `zh-CN` | Chinese (Simplified, China)      |
| `zh-TW` | Chinese (Traditional, Taiwan)    |
| `zh-HK` | Chinese (Traditional, Hong Kong) |

## What gets translated

| Surface                                            | Translated?                                                   |
| -------------------------------------------------- | ------------------------------------------------------------- |
| Unsubscribe footer on marketing emails             | Yes                                                           |
| Hosted unsubscribe / subscribe / preferences pages | Yes                                                           |
| **Your own template subject and body**             | No — author per-language templates and branch on `{{locale}}` |

## Translating your own templates

Template content is yours to localize. Two approaches are common:

* **A separate template per language**, selected by your code or your workflow before the send goes out. A locale suffix in the name (`welcome-en`, `welcome-fr`) keeps them organized.
* **A single template that branches internally**, using Handlebars conditionals on `{{locale}}` to embed each language variant. Fine for a few short strings; painful once emails get long.

When there's a lot to localize, one template per language stays maintainable much longer.