Localisation / langues

La localisation est optionnelle, et n’affecte pas les champs techniques ou contractuels.

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 :

?locale=fr
?locale=en

Exemple complet :

GET https://api.discordtop.net/v7/check-vote?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 :

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

En anglais (par défaut) :

{
  "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 :

{
  "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/check-vote?discord_id=123&locale=fr

Réponse :

{
  "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.