KiaroSama/Revayat-Skill

Revayat — Tradução de livros Inglês → Persa

Execute os nove passos abaixo em ordem. Cada um é um comando mais uma regra sobre o que fazer com sua saída. Não improvise uma ordem diferente e não pule uma etapa porque a anterior pareceu correta.

Defina duas variáveis uma vez e depois use-as em todos os lugares:

• SKILL_DIR — a pasta que contém este arquivo. Em um plugin Claude Code é ${CLAUDE_PLUGIN_ROOT}/skills/revayat.
• WORK — uma pasta de trabalho para este livro, por exemplo work/.

Todo comando é python3 $SKILL_DIR/scripts/revayat.py <estágio> ….

---

As cinco regras que nunca devem ser quebradas

1. Nunca inverta texto persa para fazê-lo ser lido da direita para a esquerda. A direção é definida pelo construtor. Inverter produz um arquivo que funciona em apenas um visualizador.
2. Nunca invente, remova, mescle, divida ou reordene um cabeçalho @@ id. Devolva exatamente os que você recebeu.
3. Nunca remova um marcador [[fn:…]], **negrito**, *itálico* ou `verbatim`. Eles são contados; uma diferença falha na QA.
4. Nunca edite manualmente book.json para corrigir uma tradução. Corrija a planilha e execute a mesclagem novamente.
5. Nunca encurte o livro. Sem resumos, sem pular uma frase difícil, sem suavizações. Se uma etapa relatar conteúdo faltando, execute novamente aquele pedaço.

---

Passo 1 — Verificar as ferramentas

python3 $SKILL_DIR/scripts/revayat.py doctor

• "ready": true → continue.
• "ready": false → execute pip install -r $SKILL_DIR/requirements.txt, depois execute doctor novamente.
• optional_tools mostrando not found está ok por enquanto. O Passo 2 dirá se OCR é realmente necessário.

Passo 2 — Extrair

python3 $SKILL_DIR/scripts/revayat.py extract "<arquivo de entrada>" --out $WORK

Para uma fonte em persa, adicione --ocr-lang fas. Para outras línguas, use o código Tesseract (deu, fra, ara, …).

Leia o JSON que ele imprime e siga a tabela:

O que você vê	O que fazer
"kind": "digital"	nada; nenhum OCR foi necessário
"kind": "scanned" ou "mixed"	OCR executado automaticamente; verifique se ocr.probe_after.text_share está acima de 0.7
um erro nomeando OCRmyPDF	instale-o conforme a mensagem, depois execute novamente esta etapa
clean_scan.cleaned acima de 0	uma marca d'água colorida foi removida dessas páginas
ocr.warning não é nulo	leia-o; o arquivo ainda era utilizável, então continue
page_scans_dropped acima de 0	essa quantidade de rasters de páginas inteiras foi reconhecida como a própria digitalização, não como imagens

O limpador nunca edita seu arquivo: o original permanece intocado e a cópia limpa é salva em $WORK/cleaned.pdf, com um registro por página em clean_scan do que foi removido e do que foi mantido. Passe --clean-scan off para pular completamente, ou --clean-scan force quando uma marca d'água sobreviveu.

Se o livro foi digitalizado, faça estas duas passagens extras agora.

Confiança do reconhecimento — sem ela, uma palavra mal lida é indistinguível de uma correta, porque ambas estão em persa fluente:

python3 $SKILL_DIR/scripts/revayat.py ocr-sidecar   --pdf $WORK/ocr.pdf --out $WORK --lang fas --book $WORK/book.json

Isso escreve source.ocr.json (por palavra, linha, bloco e página: caixa, confiança, ordem de leitura e qual pré-processamento foi executado) e source.ocr.txt, depois marca cada bloco em book.json com a confiança da região de onde veio. Blocos classificados como low são reportados pelo qa check como ocr-low-confidence, e aceitar um significa olhar a imagem da página. Os limites padrão são 85 e 60 e podem ser ajustados com --high / --low.

Ilustrações dentro de uma digitalização — uma página digitalizada é uma imagem plana, então uma fotografia nela não é uma imagem separada até que algo a encontre:

mineru -p $WORK/cleaned.pdf -o $WORK/mineru -b pipeline -l arabic
python3 $SKILL_DIR/scripts/revayat.py extract "<arquivo de entrada>" --out $WORK   --figures-from-mineru $WORK/mineru

Execute MinerU em cleaned.pdf, não no original, ou ele cortará a marca d'água como se fosse uma figura. Pegue apenas as imagens do MinerU. O texto reconhecido por ele para persa volta com as palavras e as letras dentro delas invertidas; Tesseract com fas lê a mesma página corretamente, então o texto permanece onde está. Use --figures-page-offset N quando MinerU foi executado em um intervalo de páginas.

Depois veja o resultado antes de prosseguir:

python3 $SKILL_DIR/scripts/revayat.py qa check --book $WORK/book.json --allow-incomplete

Ignore untranslated-block aqui — nada está traduzido ainda. Você está procurando por asset-missing. Se stats.text_blocks estiver abaixo de 20 para um livro real, a extração falhou: veja references/extraction.md.

Passo 3 — Glossário

python3 $SKILL_DIR/scripts/revayat.py glossary scan \
  --book $WORK/book.json --out $WORK/glossary.json

O relatório lista needs_persian, mais frequentes primeiro. Abra $WORK/glossary.json e para cada uma das primeiras 20 entradas preencha quatro campos:

"target":      "الیزابت بنت",
"later_form":  "الیزابت بنت",
"first_form":  "الیزابت بنت (Elizabeth Bennet)",
"locked":      true

Deixe first_block_id exatamente como está — o pipeline usa isso para decidir qual único bloco introduz o nome. Não edite e não decida primeiras menções você mesmo.

Exclua entradas que não são nomes reais. Depois continue.

Passo 4 — Dividir em chunks

python3 $SKILL_DIR/scripts/revayat.py chunk build \
  --book $WORK/book.json --out $WORK/chunks --glossary $WORK/glossary.json

Anote o número de chunks. Cada um se torna uma tarefa de tradução.

Se você já traduziu algumas planilhas e uma entrada mudou desde então, isso recusa com "refused": "stale-worksheets" em vez de lhe entregar silenciosamente planilhas que não correspondem mais ao livro. Releia o motivo que ele dá; adicione --force apenas depois de decidir que as traduções existentes ainda são boas.

Passo 5 — Traduzir

Para cada $WORK/chunks/chunkNNNN.md, produza $WORK/chunks/out_chunkNNNN.md. Use um subagente separado por chunk quando sua runtime os tiver, 8 de cada vez. Se não tiver, faça um de cada vez — o resultado é o mesmo, apenas mais lento.

Dê ao subagente exatamente isto:

Leia $WORK/chunks/chunkNNNN.md e escreva $WORK/chunks/out_chunkNNNN.md.

Traduza para persa. Leia $SKILL_DIR/references/translation-policy.md primeiro e siga-o.

Formato de saída — isso é mecânico, acerte exatamente:

• Copie cada linha @@ <id> <kind> inalterada, na mesma ordem.
• Coloque a tradução persa nas linhas abaixo dela.
• Não produza mais nada: sem preâmbulo, sem inglês, sem comentários, sem resumo.

Regras:

• A tabela "Nomes" é vinculativa. Onde uma linha diz "primeira menção, introduza aqui", use essa forma mais longa. Em todos os outros lugares use a forma curta. Não decida isso você mesmo — a tabela já fez isso.
• "Texto ao redor" é apenas contexto. Nunca o traduza ou copie.
• Mantenha **negrito**, *itálico*, `verbatim` e [[fn:…]] exatamente, ao redor das palavras persas equivalentes. Não adicione nem remova nenhum.
• Traduza cada unidade completamente. Nunca resuma ou pule.
• Para adicionar sua própria nota de rodapé: escreva [[fn:tr-01]] na frase e adicione um bloco @@ tr-01 footnote no final com seu texto. Apenas para uma referência cultural genuína ou jogo de palavras.

Verifique o que resta a qualquer momento:

python3 $SKILL_DIR/scripts/revayat.py chunk status --chunks $WORK/chunks

Passo 6 — Mesclar

python3 $SKILL_DIR/scripts/revayat.py merge --book $WORK/book.json --chunks $WORK/chunks

Campo	Significado	Ação
"ok": true	tudo chegou	continue para o passo 7
missing_outputs	esses chunks nunca foram traduzidos	traduza-os
missing_units	cabeçalhos foram removidos	execute novamente esses chunks
unknown_units	cabeçalhos foram inventados	execute novamente esses chunks

Executar a mesclagem novamente após uma correção é sempre seguro.

Passo 7 — Tipografia persa

python3 $SKILL_DIR/scripts/revayat.py falint fix --book $WORK/book.json

Apenas mecânico e seguro para executar duas vezes. Adicione --digits keep se o livro precisar manter numerais latinos.

Passo 8 — Portão, depois construir

python3 $SKILL_DIR/scripts/revayat.py qa check \
  --book $WORK/book.json --assets $WORK/assets --glossary $WORK/glossary.json

Não construa enquanto "ok" for falso. Corrija pelo código de erro:

Código	Significado	Ação
untranslated-block	um bloco não tem persa	traduza aquele chunk
footnote-marker-lost	um [[fn:…]] foi removido	execute novamente aquele chunk
footnote-marker-invented	um marcador aponta para nada	execute novamente aquele chunk
possible-omission	alvo muito mais curto que a fonte	leia; geralmente uma oração removida
untranslated	inglês deixado no persa	execute novamente aquele chunk
asset-missing / asset-modified	uma imagem sumiu ou foi alterada	extraia novamente
copied-source-run	uma oração da fonte está viva dentro do persa	execute novamente aquele chunk
duplicate-translation	duas fontes diferentes receberam o mesmo persa	uma resposta de planilha foi colada duas vezes; execute ambas novamente
first-mention-repeated	um nome é introduzido em mais de um lugar	mantenha o primeiro, remova os outros
image-order	as imagens estão na ordem errada no pacote	reconstrua
bookmarks-missing / bookmark-duplicate	o sumário não linkaria para lugar nenhum, ou para o lugar errado	reconstrua
emphasis-parity (aviso)	contagem de negrito/itálico alterada	verifique um; geralmente normal
glossary-drift (aviso)	um nome bloqueado foi renderizado de forma diferente	execute novamente aquele chunk
ocr-low-confidence (aviso)	o mecanismo não tinha certeza sobre este bloco	abra a imagem da página e compare

Adicione --strict para tornar os três últimos também impeditivos, para trabalhos de publicação.

Traduza o título e o autor do livro em meta.title_target e meta.author_target em book.json — essa é a única edição manual que é esperada, porque não há planilha para eles.

Depois construa:

python3 $SKILL_DIR/scripts/revayat.py build \
  --book $WORK/book.json --assets $WORK/assets --out out/book.fa.docx \
  --font "Vazirmatn" --size 11.5

Flags úteis: --font Tahoma quando o arquivo precisar ser renderizado em uma máquina sem fontes persas; --heading-size source para reproduzir os tamanhos de ponto originais dos cabeçalhos; --template ref.docx para herdar estilos de um arquivo Word existente. Lista completa em references/docx-and-ooxml.md.

Passo 9 — Verificar e relatar

python3 $SKILL_DIR/scripts/revayat.py qa docx --file out/book.fa.docx --book $WORK/book.json

Se "ok": false, corrija antes de informar ao usuário que o arquivo está pronto.

Depois relate: onde o arquivo está, quantos capítulos, imagens e notas de rodapé ele tem, qualquer coisa que a QA sinalizou e que você optou por não resolver, e esta limitação —

O Word redimensiona o texto, portanto um documento persa editável não pode ser idêntico página por página ao PDF de origem. Os bytes das imagens e o tamanho físico, a estrutura de capítulos, ênfase, notas de rodapé e links de capítulos são exatos.

---

Referências

Leia estas apenas quando a etapa apontar para elas:

• references/translation-policy.md — o que dar ao subagente de tradução
• references/persian-typography.md — RTL, ZWNJ, pontuação, scripts mistos
• references/extraction.md — roteamento de OCR, marcas d'água, livros difíceis
• references/glossary-and-voice.md — política de nomes, aliases, voz do personagem
• references/docx-and-ooxml.md — todas as opções de construção e o que produzem
• references/troubleshooting.md — as falhas que você tem mais probabilidade de encontrar