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

# Localization

> Access the API in multiple languages

## Overview

The Contazen API supports localization for error messages and responses. Currently, the API supports:

* **English** (`en`) - Default
* **Romanian** (`ro`)

## Setting the Language

There are three ways to specify your preferred language:

### 1. Accept-Language Header (Recommended)

Use the standard HTTP `Accept-Language` header:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.contazen.ro/v1/clients \
    -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
    -H "Accept-Language: ro"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.contazen.ro/v1/clients', {
    headers: {
      'Authorization': 'Bearer sk_live_YOUR_API_KEY',
      'Accept-Language': 'ro'
    }
  });
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.contazen.ro/v1/clients',
      headers={
          'Authorization': 'Bearer sk_live_YOUR_API_KEY',
          'Accept-Language': 'ro'
      }
  )
  ```

  ```php PHP theme={null}
  $ch = curl_init('https://api.contazen.ro/v1/clients');
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'Authorization: Bearer sk_live_YOUR_API_KEY',
      'Accept-Language: ro'
  ]);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  $response = curl_exec($ch);
  ```
</CodeGroup>

### 2. Query Parameter

Include the `locale` parameter in the URL:

```bash theme={null}
curl https://api.contazen.ro/v1/clients?locale=ro \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

### 3. Request Body

For POST and PUT requests, include `locale` in the JSON body:

```bash theme={null}
curl -X POST https://api.contazen.ro/v1/invoices \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "locale": "ro",
    "client_id": "9z8y7x6w5v",
    "items": [...]
  }'
```

## Priority

If multiple methods are used, the API follows this priority order:

1. Query parameter (`?locale=ro`)
2. Request body (`"locale": "ro"`)
3. Accept-Language header
4. Default to English (`en`)

## Response Header

The API includes a `Content-Language` header in all responses to indicate the language used:

```http theme={null}
HTTP/1.1 200 OK
Content-Type: application/json
Content-Language: ro
```

## Localized Elements

The following elements are localized:

### Error Messages

<CodeGroup>
  ```json English Response theme={null}
  {
    "success": false,
    "error": {
      "message": "Validation failed",
      "type": "validation_error",
      "errors": {
        "cui": "CUI/CIF is required for B2B clients",
        "address": "Address is required"
      }
    }
  }
  ```

  ```json Romanian Response theme={null}
  {
    "success": false,
    "error": {
      "message": "Validarea a eșuat",
      "type": "validation_error",
      "errors": {
        "cui": "CUI/CIF este obligatoriu pentru clienții B2B",
        "address": "Adresa este obligatorie"
      }
    }
  }
  ```
</CodeGroup>

### Field Labels

Field validation messages are localized based on the context:

| English                                | Romanian                                           |
| -------------------------------------- | -------------------------------------------------- |
| Name is required                       | Numele este obligatoriu                            |
| Invalid email format                   | Format email invalid                               |
| Invoice not found                      | Factura nu a fost găsită                           |
| Client not found                       | Clientul nu a fost găsit                           |
| Due date cannot be before invoice date | Data scadentă nu poate fi înainte de data facturii |

## Examples

### Creating an Invoice with Romanian Errors

Request:

```bash theme={null}
curl -X POST https://api.contazen.ro/v1/invoices \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Accept-Language: ro" \
  -H "Content-Type: application/json" \
  -d '{
    "items": []
  }'
```

Response:

```json theme={null}
{
  "success": false,
  "error": {
    "message": "Validarea a eșuat",
    "type": "validation_error",
    "code": "invalid_request",
    "status": 400,
    "errors": {
      "items": "Cel puțin un articol este necesar",
      "client_id": "Clientul este obligatoriu"
    }
  },
  "meta": {
    "version": "v1",
    "response_time": "12.34ms"
  }
}
```

### Retrieving Non-existent Client

Request:

```bash theme={null}
curl https://api.contazen.ro/v1/clients/invalid_id?locale=ro \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

Response:

```json theme={null}
{
  "success": false,
  "error": {
    "message": "Clientul nu a fost găsit",
    "type": "not_found_error",
    "code": "resource_not_found",
    "status": 404
  },
  "meta": {
    "version": "v1",
    "response_time": "8.91ms"
  }
}
```

## Language Detection

If no language preference is specified, the API attempts to detect the language from the `Accept-Language` header:

* If the header contains `ro` (e.g., `ro-RO`, `ro`), Romanian is used
* Otherwise, English is used as the default

## Best Practices

1. **Consistency** - Use the same language setting method throughout your application
2. **User Preference** - Store user language preferences and apply them to all API requests
3. **Fallback Handling** - Always handle English responses as a fallback
4. **Header Method** - Prefer the `Accept-Language` header for RESTful compliance

## Notes

<Note>
  Success messages and data field names remain in English regardless of the locale setting. Only error messages and validation messages are localized.
</Note>

<Warning>
  Not all error messages may be translated. If a translation is missing, the English version will be returned as a fallback.
</Warning>