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'

從 repository 根目錄開始，檢查 PO 檔案以及 README 中對 Documentation Contribution Agreement 的參照。使用提議的 shell pipeline 了解預期的 translator 清單，然後定義 get_translators.py 以產生或更新 TRANSLATORS，同時處理重複項目、排除的 bot credit 和缺少的 email。產生的檔案反映所有符合條件的 PO credit 即表示完成。