Internacionalização

Novo na versão 1.1.

Complementarmente às traduções fornecidas pelas mensagens geradas pelo Sphinx, algumas barras e botões de navegaçã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 Sphinx

gettext [1] é um padrão para internacionalização e localização (acepção sua localidade). Nativamente mapeia mensagens em um programa para uma frase traduzida. Sphinx usa essas facilidades para todos os documentos.

Inicialmente os mantenedores do projeto, coletam todas as palavras ou frases que serão traduzidas (também referidas como mensagens) para torná-las conhecidas para os tradutores. Sphinx extraí isso através da chamado do comando sphinx-build -b gettext.

Cada simples elemento do (doctree raíz do documento) irá gerar uma simples mensagem a qual resultará em listas que serão 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 será encontrada uma coleção de arquivos .pot em seu diretório de saida. Essas mensagens são chamadas de catálogos modelo 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 — chamados catálogos de mensagens — contendo um mapeamento das mensagens originais para palavras-frases na língua estrangeira.

O gettext os compila em um formato binário conhecido como binary catalogs 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:

  • Compilar catálogo de mensagem em um diretório específico, digamos locale o qual irá ficar em ./locale/es/LC_MESSAGES/usage.mo em seu diretório fonte (onde es is the language code for Spanish.)

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

  • Assinale locale_dirs para ["locale/"].

  • Definir language to ``es` (também possível via -D).

  • Execute sua montagem (executar sphinx para construir seu documento) 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. )

Novo 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á definida para _build, que locale_dirs está definida como locale/ e gettext_compact está definida como False (o documento Sphinx já está configurado como tal).

  3. Extrair mensagens traduzíveis em arquivos pot.

    $ make gettext

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

  4. Gere 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. Traduzir 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 documento traduzido.

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

    For BSD/GNU make, run:

    $ 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.

Novo 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 time tradutotes

Transifex é um dos diversos serviços que permite tradução colaborativa via interface web. Possui diversos comandos Python base que permite que clientes baixem e devolvam traduções

  1. Instale transifex-client.

    Utilizar o comando tx para fazer upload de recursos arquivos pot.

    $ pip install transifex-client

    Ver também

    Transifex Client documentation

  2. Create your Transifex account and create new project for your document.

    Currently, Transifex does not allow for a translation project to have more than one version of the document, so you’d better include a version number in your project name.

    Por exemplo:

    ID Projeto:

    sphinx-document-test_1_0

    URL 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 corrente, bem como um arquivo ~/.transifexrc que inclui informação de auth.

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

  4. Upload pot files to Transifex service.

    Registrar arquivos pot para 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 upload 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. Forward the translation on Transifex.

  6. Puxe arquivos PO traduzidos e gere o HTML traduzido.’

    Obtenha catálogos traduzidos e crie arquivos mo. Por exemplo, para construir arquivos mo para o 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.

    Invoque make html (para BSD/GNU make):

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

Isso é tudo, Pessoal!

Dica

Traduzindo localmente e no Transifex

If you want to push all language’s po files, you can be done by using tx push -t command. Watch out! This operation overwrites translations in 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.

Contribuindo para tradução Referência Sphinx

A maneira que recomendamos para novos contribuidores para traduzir o Sphinx é juntar-se a equipe e tradução do seu idioma do Transifex.

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

  1. Login to Transifex service.

  2. Ir para sphinx translation page`_.

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

  4. Wait acceptance by Transifex sphinx translation maintainers.

  5. (After acceptance) Translate on Transifex.

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

Notas de Rodapé