Cache, errors and reference
All packages follow the same flow and behave the same way on errors. This page explains it once; each guide links here.
What each run does
- Computes a hash of each source file and asks the API which ones changed.
- Sends only the texts from the files that changed.
- Requests the translation for each language and shows progress in the terminal.
- Downloads the translations and writes one file per language, with the same structure as the original.
If a text is already translated in the shared network, the API returns it instantly without using your AI key.
Cache
A second run without changes makes a single request and translates nothing.
| Package | Where the cache is |
|---|---|
| React, Next.js, Astro, Docusaurus | ~/.config/translate-projects-core/cache.json (on Windows, %APPDATA%\translate-projects-core\cache.json). It is a cache per project folder. |
| Django | locale/.translate-projects.json |
| Laravel | lang/.translate-projects.json |
Forcing a full translation
Use it, for example, after editing translations in the dashboard or changing the AI model.
| Package | How to force |
|---|---|
| Docusaurus | npx translate-projects-docusaurus --force or the option force: true |
| Django | python manage.py translate --force |
| Laravel | php artisan translate --force |
| React, Next.js, Astro | Delete ~/.config/translate-projects-core/cache.json and run again. |
Common errors
No error deletes or leaves your translated files half-done: the languages that fail keep what they had, and the ones that work are written. On error the command exits with code 1, so your CI fails too (in Astro, a partial translation is only a warning).
| Symptom | Cause | Solution |
|---|---|---|
401 or Invalid token | The API token does not exist, is disabled, or the variable was not loaded. | Check TRANSLATE_PROJECTS_API_KEY and create a new token in API Tokens if needed. |
MISSING_API_KEY on startup | The package did not find the API token. | Set TRANSLATE_PROJECTS_API_KEY (or the apiKey option). Without a token no request is made. |
MISSING_API_KEY during translation, or texts that remain in the base language | The project has no AI provider, model, or key configured. Only texts already in the network arrive. | Configure the project's AI in the dashboard and run again: the missing texts are requested again. |
| Partial translation | Some text was not translated (AI without a key, provider limit, one-off error). | The missing texts stay in the base language and are retried automatically on the next run. |
The source language is not the default | The package's base language is not the project's default language. | Use the same language on both sides. |
The target language is not active in your project | That language is disabled in the project. | Activate it in the dashboard or remove it from the target languages. |
429, 5xx or network error | The API or your connection failed. | Each request is retried 3 times. If it keeps failing, run again later. |
Quick reference
Key data for people and AI assistants integrating Translate Projects:
- The API is at
https://api.translateprojects.dev; it can be changed withTRANSLATE_PROJECTS_API_URL, for example for a local server. - Authentication: header
Authorization: Token <TRANSLATE_PROJECTS_API_KEY>. - The base language of the package must be the same as the project's default language.
- The AI (provider, model, and key) is configured in the project, never in the package.
- Language codes follow the format
es,en,fr,pt-BR.