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
  • Instalando programas necessários
  • Instalando a ferramenta de CLI do Transifex
  • Clonando o repositório
  • Entrando no diretório do repositório
  • Criando e entrando em um ambiente virtual
• Testando a tradução com os scripts
  • Definindo variáveis de ambiente
  • setup.sh - preparando checkouts locais e instalando pacotes Python
  • build.sh - gerando a documentação e relatando erros
  • lint.sh - diversas verificações de reStructuredText
  • generate_templates.sh - gerando novos POT e atualizando .tx/config
  • pull_translations.sh - baixando traduções
• Testando a tradução de outras formas
  • Obtendo branches com as traduções
  • Encontrando e removendo caracteres de espaço de largura zero
  • Verificações ortográficas

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.

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

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

Esta ferramenta é um requisito para quegenerate_templates.sh possa gerar .tx/config e para quepull_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 emConfiguraçõ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.comtoken         = 1/xxxxx

Substitua1/xxxxx pelo token de API criada.

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

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

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

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

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.

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 formatoll oull_CC (válido para aconfval 'language' do Sphinx). Usept_BR para português brasileiro. Poderia seres,fr,zh_CN, etc.
• PYDOC_REPO: URL do repositório. Usehttps://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, usepython-newest. Para outras versões, use a versão sem ponto, comopython-313,python-312 etc.
• PYDOC_VERSION: a versão do Python cuja documentação você quer traduzir. Por exemplo, você deve usarPYDOC_VERSION como3.13 caso tenha optadoPYDOC_TX_PROJECT comopython-313. Por outro lado, a versão usada para opython-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:

# .envexport PYDOC_LANGUAGE=pt_BRexport PYDOC_REPO=https://github.com/python/python-docs-pt-brexport PYDOC_TX_PROJECT=python-newestexport PYDOC_VERSION=3.14

Então, basta carregá-lo:

source .env

./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,
• usarpip 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 setx, a ferramenta de CLI do Transifex, não estiver disponível

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

./scripts/build.sh

Gera a documentação traduzida em HTML usandosphinx-build por meio domake, que usa o arquivo Makefile emcpython/Doc.

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

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

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

./scripts/lint.sh

Esse comando usasphinx-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 emlogs/sphinxlint.txt.

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

• Não precisa de passar argumentos. O diretóriocpython/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.

./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 ferramentatx esteja presente para interagir com Transifex. Se você não a instalou na seçãoInstalando 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 emcpython/Doc/build/gettext e o arquivo de configuração do Transifex fica emcpython/Doc/locales/${PYDOC_LANGUAGE}/LC_MESSAGES/.tx/config.

./scripts/pull_translations.sh

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

NOTA: esse script requer que a ferramentatx esteja presente para interagir com Transifex. Se você não a instalou na seçãoInstalando 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 recursolibrary--os do Transifex do projeto selecionado (por exemplo,python-newest).

A tradução baixada estará disponível emcpython/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.

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.

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, branch3.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-brgit clone --single-branch --branch 3.14 https://github.com/python/python-docs-pt-br python-docs-pt-br/3.14

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

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 napull request #273.