# Localisation / langues

L’API DiscordTop permet d’adapter certains champs textuels en fonction de la langue souhaitée.\
Cela permet aux intégrations (bots, sites, CMS, jeux…) d’afficher des messages ou métadonnées dans la langue préférée de leurs utilisateurs.

***

## Objectif

L’option `locale` sert à :

* personnaliser les champs **lisibles par l’utilisateur**,
* tout en gardant les champs techniques **strictement identiques** (dates, booléens, identifiants…).

Elle n’affecte pas :

* les noms d’attributs JSON,
* les codes d’erreur,
* les boolean/number/date,
* les valeurs contractuelles de l’API.

***

## Utilisation du paramètre `locale`

La langue peut être spécifiée via la query string :

```bash
?locale=fr
?locale=en
```

Exemple complet :

```bash
GET https://api.discordtop.net/v7/vote-check?api_token=xxx&discord_id=123456&locale=fr
```

***

## Langues supportées

| Code | Langue               |
| ---- | -------------------- |
| `en` | Anglais (par défaut) |
| `fr` | Français             |

Si aucune langue n’est fournie, l’API renvoie les messages en **anglais**.

***

## Champs concernés

L’option `locale` n’affecte que :

* les champs `message` dans les erreurs
* les champs textuels destinés à l’utilisateur final (lorsqu'il y a usage)

Exemple :\
Erreur `INVALID_API_TOKEN` en français :

```json
{
  "ok": false,
  "error": "INVALID_API_TOKEN",
  "message": "Le token API fourni est invalide."
}
```

En anglais (par défaut) :

```json
{
  "ok": false,
  "error": "INVALID_API_TOKEN",
  "message": "The provided API token is invalid."
}
```

Les autres champs, eux, ne changent jamais :

* `ok`
* `error`
* `guild_id`
* `has_voted`
* `last_vote_at`
* `next_vote_at`
* `cooldown_remaining_seconds`\
  → identiques dans toutes les langues.

***

## Comportement en cas de langue inconnue

Si vous fournissez une locale non reconnue :

```
?locale=jp
?locale=de
```

L’API retournera automatiquement la langue **par défaut** :

```
en
```

Exemple :

```json
{
  "ok": false,
  "error": "INVALID_API_TOKEN",
  "message": "The provided API token is invalid."
}
```

Aucune erreur spécifique n’est renvoyée.

***

## Exemple complet

#### Requête :

```
GET https://api.discordtop.net/v7/vote-check?discord_id=123&locale=fr
```

#### Réponse :

```json
{
  "ok": true,
  "has_voted": true,
  "last_vote_at": "2025-11-27T17:57:33.017+01:00",
  "next_vote_at": "2025-11-27T18:57:33.017+01:00",
  "cooldown_remaining_seconds": 3579.103
}
```

*(Aucun champ technique n’est localisé.)*

***

## Notes importantes

* Les valeurs textuelles resteront **minimales** pour éviter les ambiguïtés.
* Les identifiants d’erreurs resteront **toujours en anglais** (`INVALID_API_TOKEN`).
* La localisation évoluera dans les futures versions (ex : endpoints “human-friendly”).
* L’API n’analyse pas `Accept-Language` pour éviter les comportements imprévisibles.