Lingua

Uma ferramenta de terminal que transforma frases estudadas no Kindle ou digitadas manualmente em cartões enriquecidos para o Anki:

• frase original em inglês;
• tradução natural para pt-BR;
• até três itens de vocabulário;
• uma observação gramatical curta quando for útil;
• título, autor e posição do destaque;
• campo vazio para áudio gerado pelo HyperTTS.

Para entradas manuais, a frase digitada é preservada no rascunho e o modelo gera uma versão corrigida para o campo English exportado ao Anki. O áudio continua sendo gerado externamente pelo HyperTTS.

As entradas são enviadas ao OpenRouter em pequenos lotes. O arquivo inteiro do livro nunca é enviado, e as requisições usam data_collection: "deny" por padrão.

Instalação

É necessário Python 3.12 ou mais recente. Com uv:

uv tool install lingua-kindle
lingua --help

Para atualizar ou remover a instalação global do usuário:

uv tool upgrade lingua-kindle
uv tool uninstall lingua-kindle

Para instalar a versão que está sendo desenvolvida localmente, use uv tool install ..

Para desenvolver no repositório:

uv sync --extra dev
uv run lingua --help

Configuração inicial

Crie uma chave específica para o projeto no workspace do OpenRouter e defina um limite de gastos. Exporte a chave apenas no terminal atual ou coloque-a no gerenciador de segredos do seu shell:

export OPENROUTER_API_KEY="sua-chave"
lingua init
lingua doctor "/caminho/para/My Clippings.txt"

Como alternativa, copie .env.example para .env no diretório do projeto e preencha a chave. O .env é carregado automaticamente, não sobrescreve uma variável já definida no terminal e está ignorado pelo Git:

cp .env.example .env

O lingua init cria .lingua/config.toml e .lingua/lingua.db. A chave não é gravada nesses arquivos.

Fluxo diário

Liste os livros reconhecidos:

lingua books "/caminho/para/My Clippings.txt"

Prepare somente as entradas ainda não exportadas. Para Kindle, sem --book, a CLI mostra um menu:

lingua prepare "/caminho/para/My Clippings.txt"

Para praticar a escrita, copie o modelo entries.example.json para entries.json (que fica ignorado pelo Git) e use-o como um JSON append-only. Digite as frases sem consultar o original quando possível:

{
  "entries": [
    {"text": "I couldnt quite put my finger on what was wrong."},
    {"text": "That was unexpected.", "source": "leitura"}
  ]
}

Processe o arquivo com o mesmo comando:

cp entries.example.json entries.json
lingua prepare entries.json

O limite padrão é de cinco entradas novas por dia, compartilhado entre Kindle e JSON. Para alterar o limite de uma execução, use --limit N; --limit 0 desativa o limite explicitamente.

Abra o TSV criado em drafts/ no LibreOffice, Excel ou editor de texto. O rascunho contém TypedEnglish, com o texto original digitado, e English, com a versão corrigida. Revise os campos e marque Include como no para descartar um cartão. Preserve os nomes e a ordem das colunas.

Depois exporte:

lingua export "drafts/nome-do-livro-data.tsv"

O arquivo de exports/ já contém as diretivas de importação do Anki. As marcações só são registradas como exportadas depois que esse arquivo é gravado com sucesso.

Escolha do modelo

Antes de adotar um modelo, você pode gerar uma avaliação cega:

lingua evaluate "/caminho/para/My Clippings.txt" --sample 12

Preencha todas as colunas Translation Score e Teaching Score com notas de 1 a 5. Em seguida:

lingua select-model "evaluations/relatorio.tsv"

O vencedor é definido pela maior média; em caso de empate, ganha o candidato de menor custo reportado. O modelo escolhido é salvo em .lingua/config.toml. A opção model também aceita um preset do workspace, como @preset/lingua-translation.

Anki e HyperTTS

Antes da primeira importação, crie o tipo de nota descrito em anki/NOTE_TYPE.md. Depois importe o TSV e gere os áudios em lote usando:

• campo de origem: English;
• campo de destino: Audio;
• voz: inglês americano (en-US).

O primeiro campo, CardID, é estável. Ao reimportar uma nota já existente, o Anki pode atualizá-la em vez de criar uma duplicata.

Comandos úteis

lingua init                       Inicializa configuração e banco
lingua doctor [INPUT]             Diagnostica Kindle ou JSON, configuração e API
lingua books CLIPPINGS            Lista livros e destaques novos
lingua prepare INPUT              Processa Kindle ou JSON e cria rascunho
lingua export DRAFT               Cria TSV final do Anki
lingua evaluate INPUT             Compara modelos às cegas
lingua select-model REPORT        Salva o modelo vencedor

Use --workspace em qualquer comando para guardar a configuração em outro diretório.

Releases para Windows e Linux

O procedimento completo está em docs/release.md.

Ao enviar uma tag no formato vX.Y.Z, o GitHub Actions testa o projeto, publica o pacote lingua-kindle no PyPI, gera executáveis nativos para Linux AMD64 e Windows AMD64 e cria a página Release com todos esses artefatos. A tag deve ter a mesma versão de pyproject.toml; por exemplo, a versão 0.2.0 exige a tag v0.2.0.

O fluxo de release usa Trusted Publishing do GitHub Actions, sem token permanente do PyPI. Antes do primeiro lançamento, configure no PyPI e no TestPyPI um publisher para este repositório, apontando para os workflows release.yml e testpypi.yml, e associe-os aos ambientes pypi e testpypi do GitHub.

Para testar uma versão em isolamento, execute manualmente o workflow TestPyPI na aba Actions. Ele publica o pacote no TestPyPI e verifica uv tool install, lingua --help e lingua doctor.

git tag v0.2.0
git push origin v0.2.0

Depois, baixe o arquivo pela página de Releases do repositório ou com a GitHub CLI:

gh release download v0.2.0 --pattern 'lingua-*'

No Linux, torne o binário executável se necessário e execute-o:

chmod +x lingua-linux-amd64
./lingua-linux-amd64 --help

No Windows, execute lingua-windows-amd64.exe pelo PowerShell ou Explorador de Arquivos.