Script Python para criar/atualizar arquivo TRANSLATORS

[rffontenelle]

Introdução

Seria interessante termos um script que extraísse a relação de tradutores que contribuíram para a documentação do Python, para fins de registro centralizado de crédito. Armazenar em um arquivo chamado TRANSLATORS parece ser o mais adequado, já que isso já é mencionado pelo Documentation Contribution Agreement no README.

Por que script Python? Primeiramente porque se trata de documentação do Python ;-) Mas o mais importante é que o Python é uma linguagem muito poderosa e multiplataforma, de forma que seria possível fazer um script de alto nível que funciona não apenas no Linux.

Idealmente, tal script Python seria utilizado em um ambiente de CI (integração contínua) para automatizar a atualização do arquivo TRANSLATORS, talvez iniciando uma pull request no caso de se achar alguma diferença para o script atual. Porém, o foco desta sugestão é apenas o script.

Sugestão de funcionamento do script

Sugere-se um script, digamos "get_translators.py", que a simples execução sem argumentos de linha de comando resulte em criar/atualizar um arquivo chamado "TRANSLATORS". Alternativamente, enviar o resultado para a saída padrão porém aceitando que se informe o arquivo de saída como parâmetro de linha de comando.

O script deve encontrar todos os arquivos PO no repositório. Isso poderia ser feito usando PathLib para encontrar os arquivos PO a partir da raiz do repositório, ou usando a biblioteca GitPython para obter os arquivos rastreados no repositório git. A primeira opção parece ser mais simples e fácil de implementar.

Detalhes técnicos dos créditos nos arquivos PO

• Transifex sempre insere os créditos de tradução no início dos arquivos PO, como um comentário (iniciando com #) antes do primeiro msgid que serve de cabeçalho. As linhas com a relação de tradutores aparece entre uma linha # Translators: e #, algo que facilita determinar o início e o fim da área de créditos de tradução.
  
  Por exemplo, o arquivo sphinx.po tem os seguintes créditos:
  

# Translators:
# Marco Rougeth <[email protected]>, 2021
# Welington Carlos <[email protected]>, 2021
# Claudio Rogerio Carvalho Filho <[email protected]>, 2021
# And Past <[email protected]>, 2021
# Adorilson Bezerra <[email protected]>, 2021
# Rafael Fontenelle <[email protected]>, 2021
#

• Nem sempre e-mail está presente no arquivo PO. Neste caso, aparece somente o nome e ano de contribuição. Por exemplo:

# Foo <[email protected]>, 2021
# Bar, 2021

• Contas Transifex excluídas aparecem como hashes no nome e no e-mail (se estiver presente). Por exemplo:

01419cbcade949a3bc5433893a160e74, 2021
2c4b5a73177ea5ea1d3324f10df471a7_b8aeba7 <7df8a60bac356f3b148ac94f3c2796f6_834576>, 2021

• Um(a) contribuidor(a) pode aparecer mais de uma vez com diferenças no nome ou no e-mail, sendo interessante filtrar essas ocorrências para evitar adição duplicada. Por sorte, devem ser raros os casos. Exemplo de duplicidade:

Willian C Lopes <[email protected]>
Willian Lopes

• Excluir da saída do script o "tradutor" i17obot <[email protected]>, visto se tratar de uma conta de bot e não uma pessoa.
• Um combinação de comandos Shell do Linux para obter a lista de contribuidores de todos os arquivos PO, executado da raiz do repositório, seria:

for pofile in $(find -name '*.po')
do
    sed -n '/# Translators:/,/^#$/p' $pofile | sed 's|^# ||;s|, [0-9][0-9][0-9][0-9]$||'
done | sort -u | sed '/# Translators:/d;/^#$/d;/i17obot <[email protected]>/d'