Guia de teste

Este é um guia de teste da tradução da documentação do Python.

Testar a tradução, em que pese não ser obrigatório, ajuda a garantir tradução conforme contexto, a garantir a correta conjugação verbal em cada caso, a evitar erros de sintaxe ReStructuredText e outros erros.

• Preparando o ambiente
  • Sistema operacional
  • Instalar programas necessários
  • Configurar transifex-client
  • Clonar o repositório
• Testando tradução
  • Compilar a documentação traduzida
  • Baixar uma tradução do Transifex
  • Servir em um servidor web local
  • Verificar ortografia
    • make spell
    • pospell

Preparando o ambiente

Sistema operacional

Atualmente, a maioria destas instruções são compatíveis apenas com Linux, de forma que Windows e macOS não funcionarão sem ajustes no sistema (não testados e, portanto, não abordados aqui).

Instalar programas necessários

Os seguintes comandos devem estar disponíveis para os testes funcionarem:

• msgcat e outras ferramentas incluídas no Gettext (normalmente já instalado nas distros Linux)
• git
• make
• python3

Configurar a ferramenta de linha de comando do Transifex

Esta seção fornece os passos para configuração do tx, a ferramenta de linha de comando do Transifex.

1. Gere um token de API no Transifex em Definições do utilizador > Chave de API (link direto). Copie-o imediatamente após criar, pois só será mostrado uma vez!
2. Crie o arquivo ~/.transifexrc com seu token de API e seu nome de usuário:

[https://www.transifex.com]
rest_hostname = https://rest.api.transifex.com
token         = 1/xxxxx

Substitua 1/xxxxx pela chave de API criada.

Consulte a seção página da ferramenta tx para mais informações.

Clonar o repositório do projeto

Escolha um diretório onde gostaria de manter a cópia local do repositório e execute:

git clone https://github.com/python/python-docs-pt-br

Não é necessário clonar o repositório repositório do cpython, pois os alvos do Makefile deste projeto já fazem a clonagem automática do cpython.

Testando tradução

Compilar a documentação traduzida

NOTA: Este comando não baixa traduções do Transifex. Para isso, vejo os comandos da seção a seguir. Dentro do diretório python-docs-pt-br, execute:

make build

Este comando vai instalar pacotes do PyPI, clonar o repositório cpython (Se necessário e demais ajustes necessários, para então compilar a documentação. Caso haja erro de sintaxe reStructuredText, os avisos que seriam emitidos pelo sphinx-build serão tratados como erros por padrão por SPHINXERRORHANDLING estar definida com a opção -W.

Para ter avisos apenas como avisos durante o processo de compilação, limpe o valor da variável SPHINXERRORHANDLING:

make build SPHINXERRORHANDLING=''

Avisos são, por padrão, tratados como erro. Então, havendo um erro de sintaxe ReStructuredText que é considerado aviso, será mostrado como erro.

Baixar a tradução atualizada

Dentro do diretório python-docs-pt-br, execute:

make pull

Este comando baixar as traduções para português brasileiro da documentação do Python que estão armazenadas no Transifex. Antes disso, o comando vai preparar o ambiente instalando dependências e preparando o checkout do cpython.

Baixar uma tradução do Transifex

Isto é muito útil quando se deseja testar uma tradução específica que ainda não foi publicada, mas que está no Transifex.

Antes de baixar a tradução, certifique-se de ter os pacotes do PyPI instalados no ambiente virtual, executando:

make venv 

Então, o comando é o seguinte:

venv\bin\tx -fr <projeto>.<recurso>

sendo <projeto> sempre python-newest, que é o projeto ("versão") que deve receber tradução, e <recurso> o nome do recurso que você traduziu no Transifex, como library--os, reference--datamodel, whatsnew--3_9 etc.

Por exemplo, para baixar a tradução de library--os, o comando seria:

venv\bin\tx -fr python-newest.library--os

Baixado com sucesso, agora você pode Compilar a documentação traduzida. Em seguida, pode Servir em um servidor web local.

Servir em um servidor web local

Para ver como a documentação traduzida compilada ficou, você pode iniciar um servidor web local com um simples comando.

Mas antes de servir, certifique-se de Compilar a documentação traduzida.

Para servir a documentação, execute:

make serve

Sua documentação deve estar disponível em http://localhost:8000.

Verificar ortografia

Erros de escrita acontecem, então é sempre interessante fazer uma varredura na documentação para encontrá-los e corrigi-los.

Veja a seguir algumas formas de fazer esta verificação.

make spell

Para verificar ortografia de toda a documentação traduzida, basta executar:

make spell

Uma vez terminada a operação, um diretório .pospell listará os erros de escrita da seguinte forma:

• .pospell/typos.txt: um arquivo texto com todos os erros de escrita encontrados, mostrando apenas uma vez cada ocorrência de erro.
• .pospell/out/<nome-arquivo>.txt: um arquivo txt para cada arquivo .po disponível no diretório python-docs-pt-br, listando os erros de escrita do respectivo arquivo .po.

pospell

Para verificar a ortografia de apenas um arquivo, em vez de verificar toda documentação com make spell, pode-se usar a ferramenta pospell:

venv\bin\pospell -l pt_BR -p dict <nome-do-arquivo>.po

sendo dict o nome do arquivo de dicionário localizado no repositório python-docs-pt-br, e <nome-do-arquivo>.po o arquivo .po que você deseja testar.

Por exemplo, seu quiser verificar a ortografia da biblioteca os, cuja tradução encontra-se em library/os.po, o comando seria:

venv\bin\pospell -l pt_BR -p dict library/os.po

O resultado será emitida para a saída padrão (stdout).