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.

Uma vez compilada a documentação, você pode [Ver a documentação no navegador].

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 tradução de um ou mais recursos específicos do Transifex

Em vez de baixar todas as traduções por meio do comando acima, você pode querer baixar um ou mais recursos de tradução para teste ou outro motivo.

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:

tx -f -l pt_BR -r <p1>.<r1> [<p2>.<r2> <p3>.<r3> ... <pn>.<rn>]

sendo <p> referente ao projeto python-newest, que é o projeto ("versão") que deve receber tradução, e <r> 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:

tx -f -l pt_BR -r python-newest.library--os python-newest.whatsnew--3_11

Os arquivos "library/os.po" e "whatsnew/3.11.po" devem conter seu conteúdo atualizado do Transifex.

Baixado com sucesso, agora você pode Compilar a documentação traduzida. Em seguida, você pode [Ver a documentação no navegador].

Ver a documentação no navegador

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

Para servir a documentação, execute:

make htmlview

Será aberto seu navegador web na página inicial da documentação compilada localmente.

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).