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

# Localization and internationalization

> Standards for localized response messages and language negotiation.

# Localization and internationalization

## Localization and internationalization (i18n)

All REST APIs should support localized, human-readable messages (success, error, validation). Localization applies only to message strings, never to API contracts or machine-readable fields.
If you do not want to be as dynamic, at least make sure to include English readable messages.

### Request language negotiation

APIs must determine the response language using the standard HTTP request header Accept-Language.

The value must follow BCP 47 language tags (RFC 5646).

Examples:

```http theme={null}
Accept-Language: de-DE
Accept-Language: de-DE,de;q=0.9,en-US;q=0.8,en;q=0.7
Accept-Language: en
```

### Language resolution rules (mandatory)

Resolve the response language in this order:

1. Accept-Language header
2. Fallback to default language en

If the requested language is not supported, the API must fall back to English and continue processing.

### Response language declaration

Return the resolved language via Content-Language.

```http theme={null}
Content-Language: de-DE
```

### What must be localized

Localize:

* message fields in success responses
* message fields in error responses
* Validation error messages
* Human-readable descriptions

Must not be localized:

* Field names
* JSON keys
* Error keys or error codes
* Enum values
* IDs, UUIDs, technical identifiers

### OpenAPI documentation

The OpenAPI generator automatically documents an optional `Accept-Language` request header parameter and a `Content-Language` response header on every operation. This can be disabled by passing `documentLocaleHeaders: false` to the `OpenAPIGenerator` constructor.