Cache, erreurs et référence
Tous les paquets suivent le même flux et se comportent de la même façon face aux erreurs. Cette page l'explique une fois ; chaque guide renvoie ici.
Ce que fait chaque exécution
- Calcule un hash de chaque fichier source et demande à l'API lesquels ont changé.
- Envoie uniquement les textes des fichiers qui ont changé.
- Demande la traduction de chaque langue et affiche la progression dans le terminal.
- Télécharge les traductions et écrit un fichier par langue, avec la même structure que l'original.
Si un texte est déjà traduit sur le réseau partagé, l'API le renvoie immédiatement sans utiliser ta clé d'IA.
Cache
Une deuxième exécution sans changement fait une seule requête et ne traduit rien.
| Paquet | Où se trouve le cache |
|---|---|
| React, Next.js, Astro, Docusaurus | ~/.config/translate-projects-core/cache.json (sous Windows, %APPDATA%\translate-projects-core\cache.json). C'est un cache par dossier de projet. |
| Django | locale/.translate-projects.json |
| Laravel | lang/.translate-projects.json |
Forcer une traduction complète
Utilise-la, par exemple, après avoir modifié des traductions dans le panneau ou changé de modèle d'IA.
| Paquet | Comment forcer |
|---|---|
| Docusaurus | npx translate-projects-docusaurus --force ou l'option force: true |
| Django | python manage.py translate --force |
| Laravel | php artisan translate --force |
| React, Next.js, Astro | Supprime ~/.config/translate-projects-core/cache.json et relance. |
Erreurs courantes
Aucune erreur n'efface ni ne laisse inachevés tes fichiers traduits : les langues en échec conservent ce qu'elles avaient et celles qui fonctionnent sont écrites. En cas d'erreur, la commande se termine avec le code de sortie 1, donc ta CI échoue aussi (dans Astro, une traduction partielle n'est qu'un avertissement).
| Symptôme | Cause | Solution |
|---|---|---|
401 ou Token non valide | Le jeton API n'existe pas, est désactivé ou la variable n'a pas été chargée. | Vérifie TRANSLATE_PROJECTS_API_KEY et crée un nouveau jeton dans Jetons API si nécessaire. |
MISSING_API_KEY au démarrage | Le paquet n'a pas trouvé le jeton API. | Définis TRANSLATE_PROJECTS_API_KEY (ou l'option apiKey). Sans jeton, aucune requête n'est envoyée. |
MISSING_API_KEY lors de la traduction, ou textes restés dans la langue de base | Le projet n'a pas configuré le fournisseur, le modèle ou la clé d'IA. Seuls les textes déjà présents sur le réseau arrivent. | Configure l'IA du projet dans le panneau et relance : les textes manquants sont redemandés. |
| Traduction partielle | Certains textes n'ont pas été traduits (IA sans clé, limite du fournisseur, erreur ponctuelle). | Les textes manquants restent dans la langue de base et seront retentés automatiquement lors de la prochaine exécution. |
La langue source n'est pas la langue par défaut | La langue de base du paquet n'est pas la langue par défaut du projet. | Utilise la même langue des deux côtés. |
La langue cible n'est pas active dans ton projet | Cette langue est désactivée dans le projet. | Active-la dans le panneau ou retire-la des langues cibles. |
429, 5xx ou erreur réseau | L'API ou ta connexion a échoué. | Chaque requête est réessayée 3 fois. Si elle échoue encore, relance plus tard. |
Référence rapide
Données clés pour les personnes et les assistants IA qui intègrent Translate Projects :
- L'API se trouve sur
https://api.translateprojects.dev; elle peut être modifiée avecTRANSLATE_PROJECTS_API_URL, par exemple pour un serveur local. - Authentification : en-tête
Authorization: Token <TRANSLATE_PROJECTS_API_KEY>. - La langue de base du paquet doit être la même que la langue par défaut du projet.
- L'IA (fournisseur, modèle et clé) se configure dans le projet, jamais dans le paquet.
- Les codes de langue suivent le format
es,en,fr,pt-BR.