localization-packager — skill do agente
Propósito
Ir para vários idiomas é um problema de empacotamento em torno da tradução: cada idioma deve ter os mesmos 4 arquivos, e o que volta precisa ser verificado — presença, tamanho do título, capacidade de análise de legendas, contagem de legendas, desvio de tempo das legendas. Esta ferramenta cria o plano, a planilha de transferência e a verificação estrutural a partir de UM arquivo JSON de projeto. Biblioteca padrão pura do Python; apenas local.
O princípio central de honestidade desta ferramenta: ela não traduz nada e não
julga nenhuma tradução. check verifica a estrutura — presença
de arquivos, capacidade de análise, tamanhos, tempos. Um pacote COMPLETO
pode ainda conter uma tradução ruim; apenas um leitor do
idioma pode julgar isso. Nunca relate um veredito COMPLETO como
"a tradução está boa" ou "pronto para publicar" — é
"estruturalmente completo, pronto para uma leitura de qualidade humana".
Quando usar / não usar
Use quando:
- Um vídeo ou aplicativo está sendo lançado em idiomas adicionais
e o trabalho é entregue a tradutores:
manifestpara o plano,sheetpara a transferência,checkcomo o portal de entrada do que retorna. - Um pipeline precisa de um sim/não por idioma:
checkcom saída 0 = cada idioma estruturalmente completo; saída 1 = a saída nomeia cada idioma incompleto e seus problemas exatos.
NÃO use quando:
- Você precisa da tradução em si — esta ferramenta não chama nenhuma API de tradução e não produz texto traduzido. A coluna de destino em branco é para um tradutor humano.
- Você precisa de garantia de qualidade da tradução — não há verificação ortográfica, retro-tradução ou pontuação de qualidade aqui, por design.
- Você precisa de ativos de nível de canal (banners, telas finais) ou metadados de loja de aplicativos além dos 4 arquivos empacotados — fora do escopo, deliberadamente.
Comandos
Todo comando recebe o arquivo de projeto como argumento posicional
e suporta --json.
# O plano de entrega por idioma
python3 src/localization_packager.py manifest PROJETO.json
# Planilha de transferência para o tradutor (Markdown padrão, ou CSV;
# um idioma ou todos os alvos)
python3 src/localization_packager.py sheet PROJETO.json \
[--format md|csv] [--language CODIGO]
# Validar um pacote preenchido (saída 1 quando qualquer idioma está
# incompleto; --root quando as pastas estão em outro local)
python3 src/localization_packager.py check PROJETO.json \
[--root DIR]
Campos do projeto: project (nome), source_language,
source_title, source_description,
source_thumbnail_text, source_subtitles (caminho para o
arquivo SRT de origem, relativo ao arquivo de projeto), targets — lista
de {"language", "name", "translator"?}; códigos de idioma
devem ser únicos. O arquivo é validado a cada leitura;
problemas estruturais (campos ausentes, idioma duplicado, um
SRT de origem ausente ou não analisável) são erros de saída 2 que
nomeiam o problema.
Estrutura do pacote: uma pasta por código de idioma contendo
title.txt, description.txt, subtitles.srt,
thumbnail.txt.
Regras de verificação (exatas)
Por idioma, na ordem dos arquivos:
title.txt— ausente ou vazio é um problema; o texto removido de espaços maior que 100 caracteres é um problema (100 passa, 101 sinaliza). Caracteres são pontos de código Unicode.description.txt— ausente ou vazio é um problema.subtitles.srt— ausente ou vazio é um problema; texto que não é analisado como SRT é um problema (o erro de análise é citado); uma contagem de legendas que difere da origem em mais de 25% da contagem de origem é um problema (uma diferença de exatamente 25% passa, e uma diferença menor é anotada, não sinalizada); o maior desvio de início por posição acima de 2000 ms é um problema nomeando a legenda e o desvio (exatamente 2000 ms passa; 2100 ms sinaliza como "2,1s"). O desvio pareia legendas por posição sobre o primeiro min(origem, alvo) legendas, apenas inícios.thumbnail.txt— ausente ou vazio é um problema.
Vereditos: um idioma com zero problemas é COMPLETO, caso contrário
INCOMPLETO com a contagem de problemas. check sai com 0 apenas quando
todo idioma está COMPLETO.
Esquema JSON de saída (--json)
Campos comuns: tool ("localization-packager"),
version, command, project_file (nome do arquivo), project.
manifest: source_language, source_title, source_cues,
languages — cada {language, name, translator, folder, files} onde files são os 4 arquivos devidos, cada {file, what, source_fact}.
check: source_cues, root, languages — cada
{language, name, translator, status ("complete" | "incomplete"), items, problems} onde items são os 4
resultados por arquivo {file, ok, detail} e problems lista
os detalhes com falha — além de complete, total,
all_complete e um note reiterando que a verificação é apenas
estrutural.
sheet: sheets — um por idioma alvo, cada
{language, name, translator, rows}; rows é
{n, item, timing, source, target} — 3 linhas de string (título,
descrição, miniatura) então uma linha por legenda de origem
(item = "cue N", timing = SRT "start --> end"); target
é sempre "" — a coluna em branco que o tradutor preenche.
Em caso de erro, stdout é um único objeto: {"error": "<mensagem>"}
com código de saída 2 — incluindo erros de uso do argparse em
modo --json. Nunca texto simples, nunca um traceback.
Códigos de saída
0— comando bem-sucedido; paracheck, todo idioma está COMPLETO.1— uma constatação:checkencontrou pelo menos um idioma incompleto. Não é uma falha — a lista de problemas é a lista de correções para enviar de volta ao tradutor.2— ERRO: arquivo de projeto ausente ou não é JSON válido, um campo obrigatório ausente, um idioma alvo duplicado, as legendas de origem ausentes ou não analisáveis, um--languagedesconhecido, uma flag inválida. Nenhum fato de saída pode ser citado de uma execução com falha.
Limites e regras de honestidade que o agente deve respeitar
- COMPLETO significa estruturalmente completo — nada mais. Nunca eleve para "a tradução está correta", "boa" ou "publicável". O lançamento ainda precisa de um leitor do idioma; diga isso ao relatar um pacote COMPLETO.
- INCOMPLETO é uma lista de correções, não uma falha do tradutor. Relate os problemas exatos (arquivo, número da legenda, desvio, contagem de caracteres) — eles são escritos para serem encaminhados como estão.
- A ferramenta não produz texto traduzido. A coluna de destino
de uma planilha está em branco propositalmente. Nunca a preencha com
tradução automática e apresente o resultado como saída desta ferramenta,
e nunca afirme que um pacote de idioma existe até que seus 4
arquivos estejam realmente no disco e
checktenha sido executado neles. - Sinalizações de desvio são posicionais. Se um tradutor dividiu uma legenda em duas, as legendas posteriores mudam de posição e podem ser sinalizadas; a anotação de contagem de legendas na saída fornece o contexto. Relate ambos os fatos, não apenas a sinalização.
- Apenas local: a ferramenta lê apenas o arquivo de projeto, o SRT de origem e as pastas de pacote nomeadas na linha de comando, e não envia nada para lugar nenhum.