Cache, erros e referência
Todos os pacotes seguem o mesmo fluxo e se comportam da mesma forma diante de erros. Esta página explica isso uma vez; cada guia aponta para cá.
O que cada execução faz
- Calcula um hash de cada arquivo de origem e pergunta à API quais mudaram.
- Envia apenas os textos dos arquivos que mudaram.
- Solicita a tradução de cada idioma e mostra o progresso no terminal.
- Baixa as traduções e grava um arquivo por idioma, com a mesma estrutura do original.
Se um texto já estiver traduzido na rede compartilhada, a API o devolve na hora sem usar sua chave de IA.
Cache
Uma segunda execução sem mudanças faz uma única requisição e não traduz nada.
| Pacote | Onde fica o cache |
|---|---|
| React, Next.js, Astro, Docusaurus | ~/.config/translate-projects-core/cache.json (no Windows, %APPDATA%\translate-projects-core\cache.json). É um cache por pasta de projeto. |
| Django | locale/.translate-projects.json |
| Laravel | lang/.translate-projects.json |
Forçar uma tradução completa
Use-o, por exemplo, depois de editar traduções no painel ou de trocar o modelo de IA.
| Pacote | Como forçar |
|---|---|
| Docusaurus | npx translate-projects-docusaurus --force ou a opção force: true |
| Django | python manage.py translate --force |
| Laravel | php artisan translate --force |
| React, Next.js, Astro | Apague ~/.config/translate-projects-core/cache.json e execute novamente. |
Erros comuns
Nenhum erro apaga nem deixa pela metade seus arquivos traduzidos: os idiomas que falham mantêm o que tinham e os que funcionam são gravados. Diante de um erro, o comando termina com código de saída 1, então seu CI também falha (no Astro, uma tradução parcial é apenas um aviso).
| Sintoma | Causa | Solução |
|---|---|---|
401 ou Token inválido | O token de API não existe, está desativado ou a variável não foi carregada. | Verifique TRANSLATE_PROJECTS_API_KEY e crie um token novo em Tokens API, se necessário. |
MISSING_API_KEY ao iniciar | O pacote não encontrou o token de API. | Defina TRANSLATE_PROJECTS_API_KEY (ou a opção apiKey). Sem token, nenhuma requisição é feita. |
MISSING_API_KEY na tradução, ou textos que continuam no idioma base | O projeto não tem configurados o provedor, o modelo ou a chave de IA. Só chegam os textos que já estavam na rede. | Configure a IA do projeto no painel e execute novamente: os textos que faltam são solicitados outra vez. |
| Tradução parcial | Algum texto não foi traduzido (IA sem chave, limite do provedor, erro pontual). | Os textos que faltam permanecem no idioma base e são tentados novamente na próxima execução. |
O idioma de origem não é o padrão | O idioma base do pacote não é o idioma padrão do projeto. | Use o mesmo idioma nos dois lados. |
O idioma de destino não está ativo no seu projeto | Esse idioma está desativado no projeto. | Ative-o no painel ou remova-o dos idiomas de destino. |
429, 5xx ou erro de rede | A API ou sua conexão falharam. | Cada solicitud se reintenta 3 veces. Si sigue fallando, vuelve a ejecutarla más tarde. |
Referência rápida
Datos clave para personas y asistentes de IA que integren Translate Projects:
- La API está en
https://api.translateprojects.dev; se puede cambiar conTRANSLATE_PROJECTS_API_URL, por ejemplo para un servidor local. - Autenticação: cabeçalho
Authorization: Token <TRANSLATE_PROJECTS_API_KEY>. - O idioma base do pacote deve ser o mesmo que o idioma padrão do projeto.
- A IA (provedor, modelo e chave) é configurada no projeto, nunca no pacote.
- Os códigos de idioma seguem o formato
es,en,fr,pt-BR.