Guia de Tradução do Guia de Pacotes Python#
Este guia vai ajudar você a começar a contribuir com a tradução do Guia de Pacotes Python.
O processo de contribuição com a tradução do guia é parecido com o de contribuir com o próprio guia, mas em vez de trabalhar diretamente nos arquivos fonte do guia, você trabalhará nos arquivos de tradução.
Status da Tradução#
O gráfico de status das traduções é atualizado sempre que é feito o build do guia com as traduções. O status pode ser conferido em este link
Visão Geral do Processo de Tradução#
O processo de adaptação de um software para diferentes idiomas é chamado de internacionalização, ou i18n. A internacionalização permite que a tradução seja feita sem modificar o código fonte, ou no nosso caso, os arquivos fonte originais do guia em inglês.
O Sphinx, mecanismo de documentação que usamos para fazer o build do Guia de Pacotes Python, oferece suporte nativo à internacionalização, por isso o workflow é bem simples.
O processo de traduzir o guia para diferentes idiomas é chamado de localização, ou l10n. É nessa etapa que a sua contribuição entra.
Veja uma visão geral de como funciona o processo de tradução:
O guia é escrito originalmente em inglês e armazenado em um conjunto de arquivos Markdown.
Os arquivos fonte são processados pelo Sphinx para gerar um conjunto de arquivos de tradução armazenados em uma pasta para cada idioma de destino.
Quem contribui (como você!) traduz esses arquivos para os diferentes idiomas.
Durante o build do guia, o Sphinx cria uma versão no idioma original (inglês) e versões traduzidas para os idiomas definidos na configuração.
Nota
Você não precisa entender os detalhes técnicos para contribuir, mas se quiser saber como o Sphinx lida com internacionalização e localização, consulte mais informações aqui.
Duas Formas de Contribuir com uma Tradução#
Há duas formas de contribuir com uma tradução, e a primeira não exige a instalação de nada no seu computador.
Pelo site do GitHub. Os arquivos de tradução são arquivos de texto simples, então você pode editá-los diretamente no navegador. Faça um fork do repositório, edite nele um arquivo .po, depois abra um pull request. Esse é o melhor ponto de partida para a sua primeira contribuição open source. O guia de contribuição explica o workflow pelo navegador em Como contribuir pelo site do GitHub. Depois de criar um fork, você pode ir direto para Como editar os arquivos de tradução.
Com uma cópia local no seu computador. Essa opção exige mais configuração, mas permite conferir quanto de um arquivo já foi traduzido com sphinx-intl stat e visualizar o guia traduzido no navegador antes de abrir um pull request. Escolha essa alternativa se pretende traduzir muitas strings ou quer ver o seu trabalho em contexto.
Como Configurar o Ambiente Local#
Esta etapa só é necessária se você escolheu a segunda abordagem acima.
A configuração do ambiente de tradução é igual à de qualquer outra contribuição para o guia, então em vez de repetir as instruções aqui, siga estas seções do guia de contribuição nesta ordem:
Crie um ambiente virtual, que apresenta os comandos para Windows e macOS/Linux
Nota
A instalação das dependências de desenvolvimento disponibiliza sphinx-intl e nox no seu ambiente. Ambas as ferramentas são usadas mais adiante neste guia: sphinx-intl informa quanto de cada arquivo foi traduzido, e nox faz o build do guia para você visualizar o seu trabalho.
Como Iniciar uma Tradução para um Novo Idioma#
Se você pretende trabalhar em uma tradução existente, pule esta etapa e vá direto para a próxima seção.
Importante
Se quiser iniciar a tradução do guia para um novo idioma, comece criando uma issue no repositório.
Para gerar os arquivos de tradução de um novo idioma, adicione-o à lista languages no arquivo de configuração conf.py. O Nox é a ferramenta usada para gerenciar o build do guia e das traduções, e lê essa lista em conf.py.
Em conf.py, localize a lista languages e adicione o código de duas letras correspondente. Por exemplo, para iniciar a tradução do guia para francês, adicione 'fr':
# all languages that have .po files generated for them
# (excluding english)
languages = ["es", "ja", "pt", "fr"]
Nota
Você encontra uma lista das opções de idioma de duas letras do Sphinx aqui.
Como Preparar os Arquivos de Tradução#
Os arquivos de tradução contêm o texto original em inglês e um espaço para inserir o texto traduzido. Antes de começar, confirme se esses arquivos estão atualizados com as alterações mais recentes do guia.
Para isso, execute o comando abaixo e substitua LANG pelo código do idioma em que você trabalhará (e.g., es para espanhol):
nox -s update-language -- LANG
Esse comando criará os arquivos de tradução caso ainda não existam, ou os atualizará com as alterações mais recentes caso já existam.
Os arquivos de tradução são arquivos de texto com a extensão .po, armazenados em ./locales dentro das pastas correspondentes a cada idioma. Por exemplo, os arquivos da tradução para espanhol ficam no diretório locales/es/LC_MESSAGES.
Como os arquivos de tradução mapeiam o texto original em inglês para o texto traduzido, às vezes são chamados de arquivos de «catálogo» ou de «portable object».
Nota
Você não precisa conhecer todos os detalhes do formato PO para traduzir. Se quiser saber mais, consulte a documentação do GNU gettext.
Como Trabalhar em uma Tradução#
Para começar a traduzir, acesse dentro de ./locales a pasta correspondente ao idioma de destino (por exemplo, ./locales/es/LC_MESSAGES/ para a tradução em espanhol).
Nessa pasta, você encontrará um conjunto de arquivos .po correspondentes às diferentes seções do guia:
$ cd ./locales/es/LC_MESSAGES/
$ ls *.po
continuous-integration.po
CONTRIBUTING.po
documentation.po
index.po
maintain-automate.po
package-structure-code.po
tests.po
TRANSLATING.po
tutorials.po
Nota
Talvez você também encontre alguns arquivos .mo na mesma pasta. Eles são versões compiladas dos arquivos .po, criadas pelo Sphinx durante o processo de build e usadas para gerar a versão traduzida do guia. São arquivos intermediários e não devem ser editados diretamente nem armazenados no repositório.
Se estiver trabalhando em uma nova tradução, escolha um dos arquivos .po para começar. Em uma tradução existente, você pode começar pelos arquivos .po que mais precisam de trabalho.
Para conferir quanto de cada arquivo já foi traduzido, use sphinx-intl stat. Você verá o número de strings traduzidas, fuzzy, e ainda não traduzidas em cada arquivo .po.
Por exemplo, para ver as estatísticas da tradução em espanhol, execute:
$ sphinx-intl stat -l es
locales/es/LC_MESSAGES/tutorials.po: 0 translated, 0 fuzzy, 950 untranslated.
locales/es/LC_MESSAGES/TRANSLATING.po: 0 translated, 0 fuzzy, 44 untranslated.
locales/es/LC_MESSAGES/package-structure-code.po: 0 translated, 0 fuzzy, 885 untranslated.
locales/es/LC_MESSAGES/CONTRIBUTING.po: 0 translated, 0 fuzzy, 38 untranslated.
locales/es/LC_MESSAGES/documentation.po: 0 translated, 0 fuzzy, 430 untranslated.
locales/es/LC_MESSAGES/tests.po: 155 translated, 2 fuzzy, 3 untranslated.
locales/es/LC_MESSAGES/index.po: 88 translated, 0 fuzzy, 5 untranslated.
O que essas categorias significam:
Strings traduzidas são aquelas que já foram traduzidas para o idioma de destino.
Strings fuzzy são aquelas que já foram traduzidas mas precisam ser revisadas porque a string original em inglês foi alterada no guia.
Strings não traduzidas são aquelas que ainda não receberam tradução.
Nota
Ao fazer o build do guia em outro idioma, o Sphinx procura as strings traduzidas na pasta correspondente dentro de ./locales/. Quando há uma tradução disponível, o Sphinx substitui o texto em inglês pelo equivalente no idioma de destino. Quando não há, usa as strings originais em inglês.
Como Editar os Arquivos de Tradução#
Você pode editar o arquivo .po em qualquer editor de texto. Se preferir, também há ferramentas como o Poedit que oferecem uma interface gráfica.
Dependendo do editor escolhido, talvez seja possível instalar um plugin ou uma extensão que ofereça destaque de sintaxe e outros recursos para trabalhar com arquivos .po. Como exemplo, há a extensão gettext para o Visual Studio Code.
Ao abrir um arquivo .po, você verá uma série de entradas como esta:
#: ../../index.md:1
msgid "pyOpenSci Python Package Guide"
msgstr ""
A primeira linha de uma entrada começa com #: e referencia o arquivo-fonte original e o número da linha da qual o texto foi extraído. Essa informação ajuda a encontrar o contexto do texto no guia.
O campo msgid contém o texto original em inglês que precisa ser traduzido. O campo msgstr é onde você insere o texto traduzido. Esse campo pode já conter texto se outra pessoa tiver traduzido a entrada.
#: ../../index.md:1
msgid "pyOpenSci Python Package Guide"
msgstr "La guía de paquetes de Python de pyOpenSci"
Às vezes, o texto original em inglês é longo demais para uma única linha e acaba dividido em várias linhas. Nesse caso, você pode manter a mesma estrutura no texto traduzido. Observe que os campos msgid e msgstr do exemplo abaixo começam com uma string vazia, indicando que o texto continua na linha seguinte.
#: ../../index.md:254
msgid ""
"Every page in this guidebook goes through an extensive community review "
"process. To ensure our guidebook is both beginner-friendly and accurate, "
"we encourage reviews from a diverse set of pythonistas and scientists "
"with a wide range of skills and expertise."
msgstr ""
"Cada página en esta guía es revisada extensamente por la "
"comunidad. Para asegurar que nuestra guía sea comprensible a los principiantes y "
"a la vez precisa, un conjunto diverso de desarrolladores y científicos con una amplia "
"gama de conocimientos y experiencia participa en el proceso."
O texto em inglês pode conter formatação Markdown, como negrito ou itálico. Mantenha essa formatação no texto traduzido, traduzindo o conteúdo dentro das marcações.
O texto em inglês também pode conter links para outras seções do guia ou para recursos externos. Mantenha os links no texto traduzido, atualizando o texto do link quando for apropriado.
#: ../../index.md:75
msgid "[What is a Python package?](/tutorials/intro)"
msgstr "[¿Que es un paquete de Python?](/tutorials/intro)"
Uma entrada pode estar marcada como fuzzy, o que significa que o texto original em inglês mudou desde que a tradução foi feita, e talvez a tradução precise de revisão. Nesse caso você verá na entrada uma linha adicional, iniciada por #,:
#: ../../tests/write-tests.md:84
#, fuzzy
msgid ""
"**Test special cases:** Sometimes there are special or outlier cases. For"
" instance, if a function performs a specific calculation that may become "
"problematic closer to the value = 0, test it with the input of both 0 and"
msgstr ""
"**Prueba casos especiales:** A veces hay casos especiales o atípicos. Por"
" ejemplo, si una función realiza un cálculo específico que puede tener "
"problemas cerca del valor = 0, pruébalo con la entrada de 0 y un valor"
" normal."
Revise a tradução, faça os ajustes necessários e remova a tag fuzzy quando estiver tudo certo.
Você também pode adicionar comentários ao arquivo de tradução, incluindo na entrada linhas que comecem com o caractere #. Isso pode ajudar a dar contexto a outras pessoas que traduzem ou revisam o conteúdo, mas costuma ser necessário apenas em situações específicas.
Importante
Ao trabalhar em uma tradução, você não deve modificar o texto original em inglês no campo msgid. Se encontrar um erro de digitação ou outro problema no texto original, considere corrigi-lo no arquivo-fonte original (use a primeira linha da entrada para localizá-lo) e envie um pull request separado.
Como Fazer o Build da Documentação Traduzida#
Quando terminar de traduzir ou quiser conferir a tradução em contexto, você pode fazer o build local do guia no seu computador, usando o comando abaixo, substituindo LANG pelo código correto do idioma (e.g., es para espanhol)
nox -s build-language -- LANG
Esse comando faz o build de uma única versão traduzida do guia: a correspondente a LANG. O resultado fica em _build/html, dentro de uma pasta com o código do idioma (e.g., es). Se você quiser fazer o build de todos os idiomas de uma só vez, use nox -s build-all-languages.
Para ver a versão traduzida do guia no navegador, abra o arquivo index.html correspondente. Por exemplo, para ver a tradução em espanhol, abra _build/html/es/index.html.
Também é possível fazer o build de uma versão live do guia que é atualizada automaticamente conforme você altera os arquivos de tradução. Para isso, use o comando nox -s docs-live-lang. Nesse caso é preciso informar o idioma do build. Por exemplo, se estiver trabalhando na tradução em espanhol, execute:
nox -s docs-live-lang -- es
Observe o -- antes do código do idioma, isso indica que os argumentos seguintes devem ser repassados para a sessão do nox e não interpretados diretamente pelo nox. Se você esquecer o --, o nox procurará uma sessão chamada “es” e informará que ela não existe.
Esse comando usa sphinx-autobuild para iniciar um servidor web local no qual você pode acessar a versão traduzida do guia. Você pode abrir o guia no navegador acessando http://localhost:8000.
Essa é uma ótima forma de acompanhar como a versão traduzida do guia fica à medida que você altera os arquivos de tradução.
Como Enviar um PR com a Sua Contribuição#
Depois de terminar a tradução e antes de enviar um pull request (PR) para a sua tradução, confirme se o build da versão traduzida do guia é concluído sem erros nem avisos e se o conteúdo aparece corretamente no navegador.
Siga estas etapas:
Faça o build das traduções do guia com os mesmos parâmetros que serão usados durante o release:
nox -s build-all-languages-test
Confirme se a saída não contém avisos nem erros. Se houver algum, corrija-o antes de enviar o PR.
Confira se a versão traduzida do guia aparece corretamente no navegador abrindo o arquivo
_build/html/<lang>/index.html, em que<lang>é o idioma no qual você trabalhou.
Se estiver tudo certo, envie um PR com as suas alterações.
Nota
Ao enviar um PR de tradução, inclua alterações de apenas um idioma. Se você trabalhou em vários idiomas, envie um PR separado para cada um.
Os PRs de tradução receberão uma label que identifica o idioma para facilitar a localização e a revisão. Por exemplo, contribuições para a tradução em espanhol receberão a label “lang-es”.
TODO: Essa classificação poderia ser automatizada com uma GitHub Action.
Ao enviar o PR, inclua uma breve descrição das alterações e qualquer contexto que possa ajudar na revisão (e.g., você traduziu novas strings, revisou entradas fuzzy, corrigiu erros de digitação, etc.)
O Processo de Revisão#
O processo de revisão de uma contribuição de tradução é parecido com o de qualquer outra contribuição para o guia.
TODO: Esta seção precisa ser mais desenvolvida, dependendo do workflow de revisão que decidirmos adotar. Outros projetos costumam designar uma pessoa para coordenar ou editar cada idioma, responsável por revisar e fazer merge das contribuições de tradução.
Cada idioma tem uma pessoa responsável pela edição que revisa e faz merge das contribuições de tradução. Essa pessoa verifica as alterações para garantir que estejam corretas e consistentes com o estilo e o tom do guia.
Às vezes a pessoa responsável pela edição pode pedir esclarecimentos ou sugerir ajustes para melhorar a tradução. Nesse caso, faça as alterações solicitadas e envie as alterações para a mesma branch em que você abriu o PR original.
Quando a pessoa responsável pela edição aprovar a tradução, ela fará merge do PR. A versão traduzida do guia ficará disponível no site da pyOpenSci assim que o idioma for publicado.
O Processo de Release#
Quando um idioma estiver pronto para entrar no ar, a equipe de manutenção adicionará o código do idioma à lista release_languages no arquivo de configuração conf.py.
Quando o build de release do guia for executado na CI, o Sphinx também gerará as versões traduzidas para os idiomas da lista release_languages.
As traduções seguem o mesmo processo de release da versão em inglês do guia, e as versões traduzidas ficam disponíveis em pastas identificadas pelo código do idioma. Por exemplo, a tradução em espanhol estará disponível em: https://www.pyopensci.org/python-package-guide/es/ quando for publicada online.
Perguntas Frequentes (FAQ)#
Como saber quais strings precisam ser traduzidas?#
Ao executar sphinx-intl stat, você verá uma lista de arquivos .po com o número de strings traduzidas, fuzzy, e ainda não traduzidas. Comece pelos arquivos que têm mais strings sem tradução.
O que acontece quando uma string é alterada no texto original em inglês?#
Se uma string for alterada na versão original em inglês, ela será marcada como fuzzy no arquivo de tradução na próxima atualização (update-language ou update-release-languages). Quem trabalha na tradução poderá revisar as entradas fuzzy e fazer os ajustes necessários para garantir que estejam corretas, antes de remover a tag fuzzy.
Como lidar com links no texto traduzido?#
Mantenha os links no texto traduzido, mas atualize o texto do link quando necessário. Por exemplo, se o texto original em inglês tiver um link para [What is a Python package?](/tutorials/intro), mantenha o link no texto traduzido e altere o texto para [¿Que es un paquete de Python?](/tutorials/intro).
Como lidar com a formatação no texto traduzido?#
Mantenha a formatação no texto traduzido, traduzindo também o conteúdo dentro das marcações. Por exemplo, se o texto original em inglês for **Test special cases:**, preserve o negrito no texto traduzido e altere o conteúdo dentro das marcações para **Prueba casos especiales:**.
Como lidar com strings longas demais para uma única linha?#
Quando o texto original em inglês é longo demais para uma linha, ele pode ser dividido em várias linhas. No arquivo .po as strings multiline são indicadas por uma string vazia nos campos msgid e msgstr, seguidas pela continuação do texto na linha seguinte. Por exemplo:
#: ../../index.md:254
msgid ""
"This is a multiple line string. The text continues on the next line."
" Notice the space in the beginning of the second line, you need to make sure"
" to account for the concatenation, there is no space inserted when starting a"
" a new line in a multiline string."
msgstr ""
Como traduzir imagens?#
Você não deve traduzir as imagens do guia. Criar versões traduzidas de imagens é um processo complexo que exige ferramentas e recursos adicionais, e em geral isso só é feito quando as imagens traduzidas são criadas junto com as originais. Na maioria das vezes, o texto ao redor da imagem é adaptado para incluir as traduções necessárias.
Em alguns casos especiais, uma imagem pode ser essencial para compreender o conteúdo. Nessas situações, a equipe de manutenção e as pessoas responsáveis pela edição cuidarão das traduções fora deste workflow.
Quero traduzir o guia para um idioma que não está na lista. Como começar?#
Se quiser iniciar a tradução do guia para um idioma que não está na lista, crie uma issue no repositório para avisar a equipe de manutenção. Isso evita trabalho duplicado e ajuda a garantir que a equipe esteja preparada para revisar a sua contribuição quando ela estiver pronta.
Como saber quando uma tradução está pronta para o release?#
Quando uma tradução estiver pronta para entrar no próximo release do guia, a equipe de manutenção adicionará o código do idioma à lista release_languages no arquivo de configuração conf.py. Isso acionará o build da tradução durante o processo de release, e a versão traduzida ficará disponível no site da pyOpenSci.
TODO: There are many approaches here, some projects release a translation as soon as some strings are translated, others wait until a certain percentage of the content is translated.
Como posso obter ajuda com a minha tradução?#
Se tiver alguma dúvida ou precisar de ajuda com a tradução, abra uma issue no repositório do Guia de Pacotes Python
Você também pode perguntar no servidor da PyOpenSci no Discord (clique aqui para entrar), onde encontrará um canal geral para dúvidas sobre o nosso workflow, processos, e ferramentas (translation-general) e canais para cada idioma em que estamos trabalhando (spanish-translation, japanese-translation, etc).