Traduzindo documentação a usar Sphinx

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

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

Se estiver a usar o serviço Read the Docs, 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 precisa - criar outro projeto, definir o seu idioma e vinculá-lo do projeto principal como uma tradução.

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

Configuração de componente

Nome do componente

Documentação

Máscara de ficheiros

docs/locales/*/LC_MESSAGES/index.po

Modelo para novas traduções

docs/locales/index.pot

Formato de ficheiro

ficheiro gettext PO

Marcadores de tradução

rst-text
Configuração da descoberta de componentes

Expressão regular para corresponder ficheiros de tradução

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

Personalizar nome do componente

Documentation: {{ component|title }}

Defina o ficheiro base para as novas traduções

docs/locales/{{ component }}.pot

Dica

Prefere que o Sphinx gere apenas um único ficheiro PO? Desde o Sphinx 3.3.0, pode fazer isso a usar:

gettext_compact = "docs"

Pode encontrar vários projetos de documentação a ser traduzidos a usar esta abordagem: