translate-book

Visão geral do skill translate-book

O que o translate-book faz

O skill translate-book é um pipeline de tradução de livros para arquivos PDF, DOCX e EPUB. Ele divide o livro de origem em blocos Markdown, traduz esses blocos em paralelo com subagentes e depois recompõe o resultado em HTML, DOCX, EPUB e PDF. Se você precisa de translate-book para trabalho de tradução em conteúdo longo, isso é útil quando um único prompt fica frágil demais ou não dura o suficiente para um livro inteiro.

Quem deve instalar

Instale o translate-book se você traduz livros, manuais ou documentos com tamanho de livro com frequência e se importa com saída reproduzível, retomada por bloco e regeneração de formatos. É uma ótima opção para quem quer um fluxo guiado, em vez de escrever um prompt de tradução do zero para cada caso. Ele é menos útil se você só precisa de um trecho curto ou de um resumo rápido.

O que o diferencia

O principal diferencial do skill translate-book é o desenho do pipeline: conversão, chunking, tradução paralela, validação por hash e reconstrução são etapas explícitas. Essa estrutura reduz a perda de contexto e ajuda a identificar blocos faltando ou desatualizados antes da montagem final. Ela também deixa a decisão de instalação mais clara do que um prompt genérico de “traduz este arquivo”, porque o repo é opinativo quanto à toolchain e aos artefatos de saída.

Como usar o skill translate-book

Instale e verifique os pré-requisitos

Use o fluxo de instalação mostrado pelo projeto e, em seguida, confirme se as ferramentas externas esperadas pelo pipeline estão disponíveis: python3, pandoc e o ebook-convert ou calibre do Calibre. Se o ebook-convert estiver ausente, a etapa translate-book install pode até concluir, mas o fluxo vai falhar na conversão; por isso, verifique primeiro o ambiente de execução.

Comece com um prompt de entrada completo

O skill funciona melhor quando você informa o caminho do arquivo, o idioma de destino e quaisquer restrições de estilo em uma única solicitação. Um bom prompt seria: Translate /path/to/book.epub into Japanese, keep technical terms consistent, preserve chapter structure, and use a formal tone. Isso dá ao translate-book usage contexto suficiente para selecionar parâmetros e evitar troca de mensagens desnecessária. Se você omitir o caminho do arquivo, o skill deve parar e pedir essa informação.

Leia os arquivos certos primeiro

Para ganhar confiança na instalação, leia primeiro SKILL.md, depois README.md, AGENTS.md e CLAUDE.md se quiser notas de implementação e testes. Neste repo, os scripts importam mais do que uma passada rápida pelo README: scripts/convert.py, scripts/manifest.py, scripts/glossary.py e scripts/merge_and_build.py explicam como os blocos são criados, rastreados, mantidos consistentes e reconstruídos. Essa é a forma mais rápida de entender se o translate-book combina com seu fluxo de trabalho.

Use um fluxo consciente de blocos

Não pense nisso como uma única chamada de tradução. O fluxo pretendido é arquivo de entrada → blocos Markdown → saída dos blocos traduzidos → livro mesclado. Ao pedir a tradução, mencione qualquer coisa que afete a qualidade dos blocos: se notas de rodapé, tabelas ou blocos de código precisam sobreviver; se nomes devem permanecer sem tradução; e se você precisa de consistência de glossário ao longo do livro inteiro. Esses detalhes ajudam os subagentes a fazer menos escolhas locais que depois entram em conflito.

Perguntas frequentes sobre o skill translate-book

O translate-book é amigável para iniciantes?

Sim, desde que você consiga fornecer um caminho de arquivo e um idioma de destino. O skill esconde o pipeline em várias etapas, mas ainda espera que você entenda restrições de nível de livro, como fidelidade de formatação e consistência terminológica. Em geral, iniciantes obtêm resultados melhores começando com um EPUB ou DOCX curto antes de tentar um PDF grande e escaneado.

Quando eu não devo usar o translate-book?

Não use para trechos curtos, tradução informal em conversa ou casos em que você só precisa da ideia geral. Ele também é uma escolha mais fraca para PDFs muito escaneados e com OCR ruim, porque a qualidade da conversão de origem vai limitar a qualidade da tradução depois. Se o arquivo de entrada não puder ser convertido com limpeza, nenhum prompt consegue recuperar totalmente a estrutura.

Em que ele é diferente de um prompt normal de tradução?

Um prompt comum geralmente traduz em uma única janela de contexto e fica vulnerável a truncamento, deriva e inconsistência terminológica. O translate-book foi construído em torno de etapas de chunking, validação e reconstrução, então é melhor para documentos longos em que a continuidade importa. O trade-off é mais configuração e mais verificação de dependências.

O translate-book funciona para qualquer par de idiomas?

O repo foi desenhado para vários idiomas de destino, mas a qualidade ainda depende da complexidade da fonte e da carga terminológica. Os melhores resultados vêm quando você especifica o código do idioma de destino e fornece orientação de glossário para termos de domínio. Em projetos pesados de tradução, essa orientação de consistência importa tanto quanto a escolha do idioma em si.

Como melhorar o skill translate-book

Dê restrições de origem mais precisas

O maior ganho de qualidade vem de dizer ao translate-book o que não pode mudar. Forneça títulos de capítulos a preservar, termos que devem ficar em inglês, transliterações preferidas, regras de formatação para tabelas ou blocos de código e qualquer nível de público, como tom acadêmico ou voltado ao leitor geral. Por exemplo: Keep API names unchanged, translate prose formally, and preserve Markdown headings exactly.

Reduza a deriva do glossário desde o início

Como o pipeline usa subagentes paralelos, a terminologia pode derivar se você não definir os termos-chave com antecedência. Antes de processar um livro grande, prepare um glossário curto de nomes, termos de produto e frases técnicas recorrentes. Isso é especialmente importante em projetos de translate-book for Translation, onde um único termo inconsistente pode se espalhar por muitos blocos.

Fique atento a falhas de conversão e chunking

Os modos de falha mais comuns são OCR quebrado, formatação de origem mal estruturada e limites de bloco que cortam tabelas ou listas de forma estranha. Se a primeira saída parecer irregular, inspecione os arquivos intermediários dos blocos e o manifesto antes de culpar a qualidade da tradução. O hábito mais útil no translate-book guide é corrigir primeiro o pipeline de origem e só depois rodar a tradução novamente em blocos limpos.

Itere na primeira saída

Depois da primeira passada, revise alguns blocos representativos em vez de olhar só o livro mesclado final. Confira aberturas de capítulo, termos do glossário, headings e qualquer trecho em que a fonte tenha formatação densa. Se precisar, rode de novo com instruções mais restritas em vez de editar o livro inteiro manualmente; essa é a forma mais rápida de melhorar a próxima execução do translate-book skill.