Internacionalização

Adicionado na versão 1.1.

Complementarmente às traduções fornecidas pelas mensagens geradas pelo Sphinx, tal como barras de navegação, o Sphinx provê mecanismos para facilitar a tradução de documentos. Veja as Opções para internacionalização para detalhes na configuração.

../../_images/translation.svg

Visualização do fluxo de trabalho de traduções no Sphinx. (A figura foi criada por plantuml.)

Detalhes da internacionalização do Sphinx

gettext [1] é um padrão estabelecido para internacionalização e localização. Ele mapeia mensagens em um programa para uma string traduzida. Sphinx usa essas facilidades para todos os documentos.

Inicialmente os mantenedores do projeto coletam todas as strings que serão traduzidas (também referidas como mensagens ou frases) para torná-las conhecidas para os tradutores. Sphinx extrai isso através da chamada de sphinx-build -M gettext.

Cada elemento individual do doctree irá gerar uma mensagem individual, a qual resulta em listas que sendo igualmente quebradas em diferentes fragmentos, enquanto grandes parágrafos irão permanecer formatados como no documento original. Isso permite atualizações perfeitas dos documentos, enquanto são mantidos os contextos que os tradutores precisam para traduzir livremente os conteúdos. A tarefa do mantenedor é quebrar em parágrafos não muito longos para que isso seja racional, pois não há nenhuma automação para isso.

Após o Sphinx executar MessageCatalogBuilder, pode-se encontrar uma coleção de arquivos .pot em seu diretório de saída. Estes são modelos de catálogos e só contêm mensagens no seu idioma original.

Esses arquivos são enviados para os tradutores que irão transformá-los em arquivos .po – os chamados catálogos de mensagens – contendo um mapeamento das mensagens originais para as strings na língua estrangeira.

O gettext os compila em um formato binário conhecido como catálogos binários usando msgfmt por motivos de eficiência. Se você tornar esses arquivos detectáveis com o locale_dirs para o seu language, o Sphinx irá buscá-los automaticamente.

Um exemplo: você tem um documento usage.rst no seu projeto Sphinx. O construtor gettext colocará suas mensagens em usage.pot. Imagine que você tenha as traduções para espanhol [2] armazenadas em usage.po – para que suas construções sejam traduzidas, é necessário seguir estas instruções:

  • Compile seu catálogo de mensagens para um diretório de localidade, digamos locale, de forma que ele fique em ./locale/es/LC_MESSAGES/usage.mo em seu diretório fonte (sendo es o código de idioma para espanhol.)

    msgfmt "usage.po" -o "locale/es/LC_MESSAGES/usage.mo"

  • Defina locale_dirs para ["locale/"].

  • Defina language para es (também possível via -D).

  • Faça a construção desejada.

Para proteger contra erros, um aviso é emitido se as referências cruzadas no parágrafo traduzido não corresponderem às do original. Isso pode ser desativado globalmente usando a variável de configuração suppress_warnings. Alternativamente, para desativá-lo apenas para uma mensagem, termine a mensagem com #noqa assim:

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse
risus tortor, luctus id ultrices at. #noqa

(Escreva \#noqa caso você queira ter “#noqa” literalmente no texto. Isso não se aplica a blocos de código, onde #noqa é ignorado porque os blocos de código não contêm referências de qualquer maneira. )

Adicionado na versão 4.5: O mecanismo #noqa.

Traduzindo com sphinx-intl

Guia rápido

sphinx-intl é uma ferramenta útil para trabalhar com o fluxo de tradução do Sphinx. Esta seção descreve uma maneira fácil de traduzir com sphinx-intl.

  1. Instale sphinx-intl.

    $ pip install sphinx-intl

  2. Adicione configurações ao conf.py.

    locale_dirs = ['locale/']   # path is example but recommended.
gettext_compact = False     # optional.

    Este estudo de caso presume que BUILDDIR está definido para _build, que locale_dirs está definido como locale/ e gettext_compact está definido como False (o documento Sphinx já está configurado como tal).

  3. Extraia mensagens traduzíveis em arquivos pot.

    $ make gettext

    Os arquivos pot gerados serão colocados no diretório _build/gettext.

  4. Gere os arquivos po.

    Nós vamos usar os arquivos pot gerados na etapa acima.

    $ sphinx-intl update -p _build/gettext -l de -l ja

    Uma vez completados, os arquivos po gerados serão colocados nos diretórios abaixo:

    • ./locale/de/LC_MESSAGES/

    • ./locale/ja/LC_MESSAGES/

  5. Traduza os arquivos po.

    Como mencionado acima, eles estão localizados no diretório ./locale/<lang>/LC_MESSAGES. Um exemplo de um tal arquivo, do Sphinx, builders.po, é fornecido abaixo.

    # a5600c3d2e3d48fc8c261ea0284db79b
#: ../../builders.rst:4
msgid "Available builders"
msgstr "<FILL HERE BY TARGET LANGUAGE>"

    Outro caso, msgid possui múltiplas linhas de texto e contém sintaxe reStructuredText:

    # 302558364e1d41c69b3277277e34b184
#: ../../builders.rst:9
msgid ""
"These are the built-in Sphinx builders. More builders can be added by "
":ref:`extensions <extensions>`."
msgstr ""
"FILL HERE BY TARGET LANGUAGE FILL HERE BY TARGET LANGUAGE FILL HERE "
"BY TARGET LANGUAGE :ref:`EXTENSIONS <extensions>` FILL HERE."

    Preste muita atenção para não quebrar a notação reST. Editores de arquivo po ajudam muito nisso.

  6. Construa o documento traduzido.

    Você precisa de um parâmetro language em conf.py ou também pode especificar o parâmetro na linha de comando.

    Para BSD/GNU make, execute:

    $ make -e SPHINXOPTS="-D language='de'" html

    Para o Windows cmd.exe, execute:

    > set SPHINXOPTS=-D language=de
> .\make.bat html

    Para o PowerShell, execute:

    > Set-Item env:SPHINXOPTS "-D language=de"
> .\make.bat html

Parabéns! O documento traduzido está no diretório _build/html.

Adicionado na versão 1.3: sphinx-build que é invocado pelo comando make e irá construir arquivos po em arquivos mo.

Se você estiver usando 1.2.x ou anterior, invoque o comando sphinx-intl build antes do comando make.

Traduzindo

Atualize seus arquivos po com os novos arquivos pot

Se um documento for atualizado, é necessário gerar arquivos pot atualizados e aplicar as diferenças aos arquivos po traduzidos. Para aplicar as atualizações de um arquivo pot ao arquivo po, use o comando sphinx-intl update.

$ sphinx-intl update -p _build/gettext

Usando o serviço Transifex para tradução em equipe

Transifex é um dos diversos serviços que permite tradução colaborativa via interface web. Possui um cliente bacana de linha de comando baseado em Python que permite baixar e enviar traduções.

  1. Instale transifex-client.

    É necessário usar o comando tx para fazer upload de recursos (arquivos pot).

    $ pip install transifex-client

    Ver também

    Documentação do Transifex Client

  2. Crie sua conta no Transifex e crie um novo projeto para sua documentação.

    Atualmente, o Transifex não permite que um projeto de tradução tenha mais de uma versão do documento, então é melhor incluir o número da versão em seu nome de projeto.

    Por exemplo:

    ID do projeto:

    sphinx-document-test_1_0

    URL do projeto:

    https://www.transifex.com/projects/p/sphinx-document-test_1_0/

  3. Crie arquivos de configuração para o comando tx.

    Esse processo irá criar .tx/config no diretório atual, bem como um arquivo ~/.transifexrc que inclui informações de autenticação.

    $ tx init
Creating .tx folder...
Transifex instance [https://www.transifex.com]:
...
Please enter your transifex username: <transifex-username>
Password: <transifex-password>
...
Done.

  4. Faça o upload dos arquivos pot para o serviço Transifex.

    Registre os arquivos pot no arquivo .tx/config:

    $ cd /your/document/root
$ sphinx-intl update-txconfig-resources --pot-dir _build/locale \
  --transifex-project-name sphinx-document-test_1_0

    e faça upload dos arquivos pot:

    $ tx push -s
Pushing translations for resource sphinx-document-test_1_0.builders:
Pushing source file (locale/pot/builders.pot)
Resource does not exist.  Creating...
...
Done.

  5. Encaminhe a tradução no Transifex.

  6. Baixe os arquivos po traduzidos e gere o HTML traduzido.

    Obtenha catálogos traduzidos e gere os arquivos mo. Por exemplo, para gerar os arquivos mo para alemão (de):

    $ cd /your/document/root
$ tx pull -l de
Pulling translations for resource sphinx-document-test_1_0.builders (...)
 -> de: locale/de/LC_MESSAGES/builders.po
...
Done.

    Execute make html (para BSD/GNU make):

    $ make -e SPHINXOPTS="-D language='de'" html

Isso é tudo, pessoal!

Dica

Traduzindo localmente e no Transifex

Se você quer enviar os arquivos po de todos os idiomas, é possível fazê-lo usando o comando tx push -t. Cuidado! Esta operação substitui as traduções no Transifex.

Em outras palavras, caso tenha atualizado cada um deles via serviço Transifex e arquivos locais po, pode ser necessário muito esforço para integrá-los.

Usando o serviço Weblate para tradução em equipe

Leia mais na documentação do Weblate.

Contribuindo para tradução das referências do Sphinx

A maneira que recomendamos para novos contribuidores para traduzir o Sphinx é juntar-se à equipe de tradução no Transifex.

Existe uma página de tradução do sphinx para a documentação do Sphinx (master).

  1. Faça login no serviço Transifex.

  2. Acesse a página de tradução do sphinx.

  3. Clique em Request language e preencha o formulário.

  4. Aguarde o aceite pelos mantenedores de tradução do Sphinx no Transifex.

  5. (Após ser aceito) Traduza no Transifex.

Detalhes aqui: https://docs.transifex.com/getting-started-1/translators

Progresso e estatísticas de tradução

Adicionado na versão 7.1.0.

Durante o processo de renderização, o Sphinx marca cada nó traduzível com um atributo translated, indicando se uma tradução foi encontrada para o texto naquele nó.

O valor de configuração translation_progress_classes pode ser usado para adicionar uma classe a cada elemento, dependendo do valor do atributo translated.

A substituição |translation progress| pode ser usada para exibir a porcentagem de nós que foram traduzidos por documento.

Notas de rodapé