Skip to content

Guia de teste

Jump to bottom
Rafael Fontenelle edited this page Oct 2, 2025 · 24 revisions

Este é um guia de teste local 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, permite realizar diagnósticos de erros inusitados, a evitar erros de sintaxe reStructuredText (reST) e outros erros.

Conteúdo:

Preparando o ambiente

Sistema operacional

Atualmente, os scripts são feitos pensando no uso em ambientes com Linux. No Windows, você pode precisar usar WSL (Subsistema do Windows para Linux) ou o Git Bash (emulador de terminal incluso no Git para Windows). O macOS, apesar de ser um "primo" originado Unix, pode ter suas diferenças ao ambiente Linux esperado, de forma que o nível de compatibilidade é desconhecida.

Instalando programas necessários

Os seguintes comandos devem estar disponíveis, presumidamente por pacotes do sistema, para os testes funcionarem:

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

Instalando a ferramenta de CLI do Transifex

Esta seção fornece os passos para configuração do tx, a ferramenta de linha de comando do Transifex (referido como "Transifex CLI tool" em inglês).

Esta ferramenta é um requisito para que generate_templates.sh possa gerar .tx/config e para que pull_translations.sh possa baixar traduções. Sua presença não é obrigatória para, por exemplo, construir a documentação, mas estes dois scripts, detalhados mais abaixo, não vão funcionar sem ela.

  1. Instale a ferramenta com:
curl -o- https://raw.githubusercontent.com/transifex/cli/master/install.sh | bash
  1. Gere um token de API no Transifex em Configurações do usuário > Token da 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 pelo token de API criada.

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

Clonando o repositório

Para ter acesso aos scripts usados mais abaixo, obtenha o repositório python-docs-pt-br com:

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

Entrando no diretório do repositório

Certifique-se de estar no diretório onde você clonou o repositório python-docs-pt-br para conseguir realizar as próximas instruções:

cd python-docs-pt-br

Criando e entrando em um ambiente virtual

Os scripts esperam que você tenha um ambiente virtual ativado para facilitar o controle de pacotes Python instalados.

Primeiro passo, crie o ambiente virtual. Caso você já tenha, pode pular para o comando seguinte (ativação). Aqui é usado o diretório .venv (diretório atual, pasta oculta) como diretório do ambiente virtual, mas sinta-se à vontade para usar em outro local.

python3 -m venv .venv

O ambiente virtual criado, agora ative-o para poder realizar as instruções das próximas seções:

source .venv/bin/activate

Testando a tradução com os scripts

O repositório python-docs-pt-br contém vários scripts Shell e Python dentro do diretório 'scripts'. A seguir, segue uma sequência de instruções de preparação até efetivamente testar.

Definindo variáveis de ambiente

Feitos para terem flexibilidade, esses scripts esperam que certas variáveis de ambiente estejam definidas para funcionarem. São elas:

  • PYDOC_LANGUAGE: código do idioma no formato ll ou ll_CC (válido para a confval 'language' do Sphinx). Use pt_BR para português brasileiro. Poderia ser es, fr, zh_CN, etc.
  • PYDOC_REPO: URL do repositório. Use https://github.com/python/python-docs-pt-br para português brasileiro.
  • PYDOC_TX_PROJECT: slug (nome para URL) do projeto de tradução no Transifex. Para o mais recente, use python-newest. Para outras versões, use a versão sem ponto, como python-313, python-312 etc.
  • PYDOC_VERSION: a versão do Python cuja documentação você quer traduzir. Por exemplo, você deve usar PYDOC_VERSION como 3.13 caso tenha optado PYDOC_TX_PROJECT como python-313. Por outro lado, a versão usada para o python-newest muda de tempo em tempo, então certifique-se de que bate ao projeto com a versão.

Uma forma de simplificar o processo é criar um .env, colocar os valores exportados dentro e carregá-los para fazer com que essas variáveis estejam disponíveis. Por exemplo, criar um .env contendo:

# .env
export PYDOC_LANGUAGE=pt_BR
export PYDOC_REPO=https://github.com/python/python-docs-pt-br
export PYDOC_TX_PROJECT=python-newest
export PYDOC_VERSION=3.14

Então, basta carregá-lo:

source .env

setup.sh - preparando checkouts locais e instalando pacotes Python

./scripts/setup.sh

Executar esse script (assim mesmo, sem argumentos) vai:

  • clonar cpython na versão desejada,
  • clonar o repositório de tradução (python-docs-pt-br ou outro idioma escolhido) no local correto e na versão desejada para passos seguintes,
  • usar pip para instalar dependências,
  • preparar dependências e ambiente do cpython
  • vai avisar se o ambiente virtual anteriormente informado não tiver sido ativado
  • vai avisar se tx, a ferramenta de CLI do Transifex, não estiver disponível

CPython será clonado para o diretório cpython, e o repositório de tradução será clonado para cpython/Doc/locales/${PYDOC_LANGUAGE}/LC_MESSAGES (portanto, se ${PYDOC_LANGUAGE} for pt_BR, é o que comporá o caminho do diretório). Essa disposição de pastas é necessária para gerar a documentação traduzida.

build.sh - gerando a documentação e relatando erros

./scripts/build.sh

Gera a documentação traduzida em HTML usando sphinx-build por meio do make, que usa o arquivo Makefile em cpython/Doc.

Avisos relacionados a erros de sintaxe reStructuredText são emitidos neste processo, o que é útil para identificar e corrigir. O arquivo de log logs/sphinxwarnings.txt contém os erros da última execução do script, se houver.

A documentação gerada é armazenada em cpython/Doc/build/html/.

Você pode abrir as páginas geradas com, por exemplo, firefox cpython/Doc/build/html/glossary.html.

lint.sh - diversas verificações de reStructured Text

./scripts/lint.sh

Esse comando usa sphinx-lint para realizar uma série de verificações de erros de tradução conhecidos em arquivos PO com tradução de reStructuredText. Problemas encontrados são armazenados em logs/sphinxlint.txt.

Vantagem desse script em comparação a executar sphinx-lint diretamente:

  • Não precisa de passar argumentos. O diretório cpython/Doc/locales/${PYDOC_LANGUAGE}/LC_MESSAGES é estático e é usado por padrão.
  • Não precisa ficar desabilitando 'unnecessary-parentheses' em versões anteriores a 3.12. Somente a partir da versão 3.12 do Python que a documentação em inglês corrigiu a verificação de parênteses desnecessários, então nas versões 3.11 usar sphinx-lint resulta em uma saída muito poluída.

generate_templates.sh - gerando novos POT e atualizando .tx/config

./scripts/generate_templates.sh

Este script interage com a documentação do CPython e com sphinx-intl para termos um .tx/config atualizado. Isso é fundamental para garantir que ao baixar traduções do Transifex, haja o correto mapeamento de todos os atuais recursos (isto é, libary--os, whatsnew/changelog e demais alvos de tradução dentro de projetos no Transifex).

NOTA: esse script requer que a ferramenta tx esteja presente para interagir com Transifex. Se você não a instalou na seção Instalando a ferramenta de CLI do Transifex, faça-o agora para usar esse script.

Tal finalidade pode não ser tão necessária, tendo em vista termos rotina diária no GitHub Actions que faz essa atualização. Mesmo assim, você pode querer ter os arquivos POT localmente.

Os arquivos POT gerados encontram-se em cpython/Doc/build/gettext e o arquivo de configuração do Transifex fica em cpython/Doc/locales/${PYDOC_LANGUAGE}/LC_MESSAGES/.tx/config.

pull_translations.sh - baixando traduções

./scripts/pull_translations.sh

Baixa toda tradução da versão selecionada se nenhum argumento é passado. "De baixo do capô", é usado o comando tx pull com mais alguns parâmetros para interagir com o Transifex.

NOTA: esse script requer que a ferramenta tx esteja presente para interagir com Transifex. Se você não a instalou na seção Instalando a ferramenta de CLI do Transifex, faça-o agora para usar esse script.

Também é possível baixar somente uma ou mais traduções específicas apenas especificando os nomes dos respectivos arquivos PO.

Por exemplo, executar:

./scripts/pull_translations.sh library/os.po

baixará traduções do recurso library--os do Transifex do projeto selecionado (por exemplo, python-newest).

A tradução baixada estará disponível em cpython/Doc/locales/${PYDOC_LANGUAGE}/LC_MESSAGES/library/os.po. Com isso, você pode fazer testes como gerar nova documentação com o script ./scripts/build.sh ou verificar ortografia com ./scripts/lint.sh.

Testando a tradução de outras formas

Os scripts contidos no repositório python-docs-pt-br têm o propósito de serem facilitadores. Mas isso não impede trabalhar de outras formas.

Obtendo branches com as traduções

Você deve ter notado que o branch main não tem traduções, pois essas ficam em branches exclusivos para cada versão. Por exemplo, branch 3.14 contém traduções para a versão 3.14 do Python.

Recomendação: clonar o repositório no branch main, e dentro clonar outros branches em subdiretórios. Desta forma, você tem acesso aos scripts, mas também ao branch diretamente, para quando/se quiser.

git clone --single-branch --branch main https://github.com/python/python-docs-pt-br
git clone --single-branch --branch 3.14 https://github.com/python/python-docs-pt-br python-docs-pt-br/3.14

Encontrando e removendo caracteres de espaço de largura zero

Uma ou mais traduções de máquinas parecem adicionar caractere de espaço de largura zero após algumas letras s.

Problema: Apesar de estranho, não parece ser malicioso. Seu único impacto conhecido é atrapalhar o casamento da tradução de um termo com respectiva entrada no glossário, gastando tempo do tradutor tentando encontrar onde teria errado na tradução.

Exemplo: "local variables" está prevista como "variáveis locais" no glossário. Um caractere de espaço de largura zero após o primeiro "s", imediatamente após a palavra "variáveis", atrapalharia o Transifex casar a tradução como correta para "local variables".

Solução: Remover ocorrências \xe2\x80\x8b com comandos como:

sed -i 's/\xe2\x80\x8b//g' caminho/para/arquivo.po

Verificações ortográficas

pospell é a ferramenta para isso, mas sem ser passado um dicionário personalizado a saída é impossível de ler -- muito falso positivo.

Atualmente temos uma solução no forno que deve simplificar este processo, tendo em visto que ela já inclui dicionários e script para facilitar este processo. Veja mais na pull request #273.

Interaja no grupo permanente no Telegram: @pybr_i18n

Achou um erro na wiki? Tem sugestão para melhorá-la? Registre uma issue.

Clone this wiki locally