Opções da CLI
Referência para o comportamento do cache translate-docs, sinalizadores, formato de prompt em lote e chaves de caminho internas do SQLite.
Comportamento do cache e sinalizadores translate-docs
A CLI mantém o rastreamento de arquivos no SQLite (hash de origem por arquivo × localidade) e linhas de segmento (hash × localidade por parte traduzível). Uma execução normal ignora um arquivo completamente quando o hash rastreado corresponde à origem atual, o arquivo de saída já existe e o tempo de modificação da saída é pelo menos tão recente quanto o da origem. Caso contrário, ele processa o arquivo e usa o cache de segmento para que o texto inalterado não chame a API. Os acertos do cache de segmento também são rejeitados quando o texto armazenado falha na validação do script. Use --check-cache para ignorar a omissão em nível de arquivo para localidades com um sistema de escrita esperado (hi, ja, zh-Hans, ar, …) para que as linhas de cache romanizadas ou com script incorreto possam ser repetidas sem --force-update.
| Sinalizador | Efeito |
|---|---|
| (padrão) | Ignora arquivos inalterados quando o rastreamento + a saída em disco correspondem; usa o cache de segmento para o restante. Acertos de cache de script incorreto são rejeitados e retraduzidos apenas para arquivos que são processados. |
-l, --locale <codes> | Localidades de destino separadas por vírgulas (quando omitidas, os padrões correspondem à união da raiz targetLocales e do docs[] opcional de cada bloco targetLocales). |
-p, --path / -f, --file | Traduzir apenas markdown/JSON sob este caminho (relativo ao projeto, absoluto ou padrão glob); --file é um alias para --path. |
--dry-run | Sem gravações de arquivos e sem chamadas à API. |
--type <kind> | Restringir a markdown ou json (caso contrário, ambos quando habilitados na configuração). |
--json-only / --no-json | Traduzir apenas arquivos de rótulos JSON, ou ignorar JSON e traduzir apenas markdown. |
-j, --concurrency <n> | Número máximo de localidades de destino em paralelo (padrão da configuração ou valor padrão embutido na CLI). |
-b, --batch-concurrency <n> | Número máximo de chamadas paralelas à API por lote por arquivo (documentos; padrão da configuração ou CLI). |
--emphasis-placeholders | Mascara marcadores de ênfase markdown como espaços reservados antes da tradução. Ativado automaticamente para localidades CJK e RTL, a menos que substituído por bloco via docs[].emphasisPlaceholders ou desativado com --no-emphasis-placeholders. |
--debug-failed | Global. Registra logs detalhados de FAILED-TRANSLATION em cacheDir para cada verificação de tradução com falha (script, análise ou qualidade incorretos), incluindo alternativas como zh-Hans/hi romanizados — não apenas quando todos os modelos falham. Erros da API do provedor são impressos no console em vez de em um arquivo. Também se aplica a sync / sync-ui / cleanup. |
--check-cache | Revalida segmentos em cache para localidades com um script nativo imposto, mesmo quando o rastreamento de arquivos seria ignorado. Localidades sem um script esperado ainda são ignoradas. O cache de segmento ainda se aplica. |
--force-update | Reprocessa todos os arquivos correspondentes (extrai, remonta, grava saídas), mesmo quando o rastreamento de arquivos os ignoraria. O cache de segmentos ainda se aplica — segmentos inalterados não são enviados ao LLM. |
--force | Limpa o rastreamento de arquivos para cada arquivo processado e não lê o cache de segmentos para tradução via API (retradução completa). Os novos resultados ainda são gravados no cache de segmentos. |
--stats | Exibe contagens de segmentos, contagem de arquivos rastreados e totais de segmentos por localidade, depois encerra. |
--clear-cache [locale] | Exclui traduções em cache (e o rastreamento de arquivos): todas as localidades ou uma única localidade, depois encerra. |
--prompt-format <mode> | Define como cada lote de segmentos é enviado ao modelo e analisado (xml, json-array ou json-object). Padrão json-array. Não altera extração, marcadores de posição, validação, cache ou comportamento de fallback — consulte Formato do prompt por lote. |
Você não pode combinar --force com --force-update (são mutuamente exclusivos).
Formato do prompt em lote
translate-docs envia segmentos traduzíveis para o provedor LLM ativo em lotes (agrupados por batchSize / maxBatchChars). O sinalizador --prompt-format apenas altera o formato de transmissão desse lote; os tokens PlaceholderHandler, as verificações AST do markdown, as chaves de cache do SQLite e o fallback por segmento quando a análise em lote falha permanecem inalterados.
| Modo | Mensagem do usuário | Resposta do modelo |
|---|---|---|
xml | Pseudo-XML: um <seg id="N">…</seg> por segmento (com escape XML). | Apenas blocos <t id="N">…</t>, um por índice de segmento. |
json-array (padrão) | Um array JSON de strings, uma entrada por segmento em ordem. | Um array JSON do mesmo comprimento (mesma ordem). |
json-object | Um objeto JSON {"0":"…","1":"…",…} indexado pelo índice do segmento. | Um objeto JSON com as mesmas chaves e valores traduzidos. |
Alguns modelos seguem um formato de forma mais confiável do que outros, então tente um modo diferente se um modelo frequentemente retornar lotes malformados ou IDs de segmento incompatíveis. json-array é o padrão porque é um formato comum e simples que os modelos geralmente lidam bem.
O cabeçalho da execução também imprime Batch prompt format: … para que você possa confirmar o modo ativo. Os arquivos de rótulo JSON (docusaurusCatalogDir) e os lotes de arquivos SVG usam a mesma configuração quando essas etapas são executadas como parte de translate-docs (ou da fase de documentos de sync — sync não expõe esse sinalizador; ele assume como padrão json-array).