Traduzindo documentação usando Sphinx

Sphinx é uma ferramenta para criar documentação bonita. Ela usa a sintaxe reStructuredText simples e pode gerar saída em muitos formatos. Se você está procurando um exemplo, esta documentação também é construída usando-a. O companheiro muito útil para usar o Sphinx é o serviço Read the Docs, que irá construir e publicar sua documentação gratuitamente.

Não vou me concentrar em escrever documentação em si, se você precisar de orientação com isso, basta seguir as instruções no site do Sphinx. Assim que você tiver a documentação pronta, traduzi-la é bastante fácil, pois o Sphinx vem com suporte para isso e é muito bem abordado em sua Internacionalização. É uma questão de poucas diretivas de configuração e invocação da ferramenta sphinx-intl.

Se estiver usando o serviço Read the Docs, você pode começar a construir a documentação traduzida no Read the Docs. Localization of Documentation (localização de documentação) deles cobre praticamente tudo que você precisa - criar outro projeto, definir seu idioma e vinculá-lo do projeto principal como uma tradução.

Agora tudo que você precisa é traduzir o conteúdo da documentação. O Sphinx gera um arquivo PO para cada diretório ou arquivo de nível superior, o que pode levar a muitos arquivos para traduzir (dependendo das configurações de sphinx: gettext_compact). Você pode importar o index.po no Weblate como um componente inicial e então configurar a extensão Descoberta de componente para descobrir automaticamente todos os outros.

Configuração de componente

Nome do componente

Documentation

Máscara de arquivo

docs/locales/*/LC_MESSAGES/index.po

Modelo para novas traduções

docs/locales/index.pot

Formato de arquivo

arquivo PO gettext

Marcadores de tradução

rst-text

Configuração de descoberta de componente

Expressão regular para corresponder aos arquivos de tradução

docs/locales/(?P<language>[^/.]*)/LC_MESSAGES/(?P<component>[^/]*)\.po

Personalizar o nome do componente

Documentation: {{ component|title }}

Define o arquivo base para novas traduções

docs/locales/{{ component }}.pot

Dica

Você prefere que o Sphinx gere apenas um único arquivo PO? Desde o Sphinx 3.3.0, você pode fazer isso usando:

gettext_compact = "docs"

Você pode encontrar vários projetos de documentação sendo traduzidos usando esta abordagem: