Script Python para criar/atualizar arquivo TRANSLATORS

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 <marco@rougeth.com>, 2021
# Welington Carlos <wcarlos3@gmail.com>, 2021
# Claudio Rogerio Carvalho Filho <excriptbrasil@gmail.com>, 2021
# And Past <andrepgs@gmail.com>, 2021
# Adorilson Bezerra <adorilson@gmail.com>, 2021
# Rafael Fontenelle <rffontenelle@gmail.com>, 2021
#

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

# Foo <foo@example.com>, 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 <willclbr@gmail.com>
Willian Lopes

• Excluir da saída do script o "tradutor" i17obot <i17obot@rougeth.com>, 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 <i17obot@rougeth.com>/d'

Inizia dalla radice del repository ed esamina i file PO e il riferimento nel README alla Documentation Contribution Agreement. Usa la pipeline shell proposta per comprendere l’elenco previsto dei traduttori, quindi definisci get_translators.py per generare o aggiornare TRANSLATORS gestendo i duplicati, i crediti dei bot esclusi e le email mancanti. Il lavoro è completato quando il file generato riflette tutti i crediti PO idonei.