mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
integrate 'translationguide.rst' into 'intl.rst'
This commit is contained in:
Takayuki Shimizukawa
@@ -23,7 +23,6 @@ Sphinx documentation contents
|
||||
faq
|
||||
glossary
|
||||
devguide
|
||||
translationguide
|
||||
changes
|
||||
examples
|
||||
|
||||
|
||||
235
doc/intl.rst
235
doc/intl.rst
@@ -15,8 +15,14 @@ in itself. See the :ref:`intl-options` for details on configuration.
|
||||
Workflow visualization of translations in Sphinx. (The stick-figure is taken
|
||||
from an `XKCD comic <http://xkcd.com/779/>`_.)
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
|
||||
Sphinx internationalization details
|
||||
-----------------------------------
|
||||
|
||||
**gettext** [1]_ is an established standard for internationalization and
|
||||
localization. It naïvely maps messages in a program to a translated string.
|
||||
localization. It naively maps messages in a program to a translated string.
|
||||
Sphinx uses these facilities to translate whole documents.
|
||||
|
||||
Initially project maintainers have to collect all translatable strings (also
|
||||
@@ -50,20 +56,239 @@ gettext builder will put its messages into ``usage.pot``. Imagine you have
|
||||
Spanish translations [2]_ on your hands in ``usage.po`` --- for your builds to
|
||||
be translated you need to follow these instructions:
|
||||
|
||||
* Compile your message catalog to a locale directory, say ``translated``, so it
|
||||
ends up in ``./translated/es/LC_MESSAGES/usage.mo`` in your source directory
|
||||
* Compile your message catalog to a locale directory, say ``locale``, so it
|
||||
ends up in ``./locale/es/LC_MESSAGES/usage.mo`` in your source directory
|
||||
(where ``es`` is the language code for Spanish.) ::
|
||||
|
||||
msgfmt "usage.po" -o "translated/es/LC_MESSAGES/usage.mo"
|
||||
msgfmt "usage.po" -o "locale/es/LC_MESSAGES/usage.mo"
|
||||
|
||||
* Set :confval:`locale_dirs` to ``["translated/"]``.
|
||||
* Set :confval:`locale_dirs` to ``["locale/"]``.
|
||||
* Set :confval:`language` to ``es`` (also possible via :option:`-D`).
|
||||
* Run your desired build.
|
||||
|
||||
|
||||
Translating with sphinx-intl
|
||||
----------------------------
|
||||
|
||||
Quick guide
|
||||
^^^^^^^^^^^^
|
||||
|
||||
`sphinx-intl`_ is a useful tool to work with Sphinx translation flow.
|
||||
This section describe a easy way to translate with sphinx-intl.
|
||||
|
||||
#. Install `sphinx-intl`_ by :command:`pip install sphinx-intl` or
|
||||
:command:`easy_install sphinx-intl`.
|
||||
|
||||
#. Add configurations to your `conf.py`::
|
||||
|
||||
locale_dirs = ['locale/'] #path is example but recommended.
|
||||
gettext_compact = False #optional.
|
||||
|
||||
This case-study assumes that :confval:`locale_dirs` is set to 'locale/' and
|
||||
:confval:`gettext_compact` is set to `False` (the Sphinx document is
|
||||
already configured as such).
|
||||
|
||||
#. Extract document's translatable messages into pot files::
|
||||
|
||||
$ make gettext
|
||||
|
||||
As a result, many pot files are generated under ``_build/locale``
|
||||
directory.
|
||||
|
||||
#. Setup/Update your `locale_dir`::
|
||||
|
||||
$ sphinx-intl update -p _build/locale -l de -l ja
|
||||
|
||||
Done. You got these directories that contain po files:
|
||||
|
||||
* `./locale/de/LC_MESSAGES/`
|
||||
* `./locale/ja/LC_MESSAGES/`
|
||||
|
||||
#. Translate your po files under `./locale/<lang>/LC_MESSAGES/`.
|
||||
|
||||
#. Build mo files and make translated document.
|
||||
|
||||
You need :confval:`language` parameter in ``conf.py`` or you may also
|
||||
specify the parameter on the command line.
|
||||
|
||||
$ sphinx-intl build
|
||||
$ make -e SPHINXOPTS="-D language='de'" html
|
||||
|
||||
|
||||
Congratulations!! You got the translated document in ``_build/html``
|
||||
directory.
|
||||
|
||||
|
||||
Translating
|
||||
^^^^^^^^^^^^
|
||||
|
||||
Translate po file under ``./locale/de/LC_MESSAGES`` directory.
|
||||
The case of builders.po file for sphinx document:
|
||||
|
||||
.. code-block:: po
|
||||
|
||||
# a5600c3d2e3d48fc8c261ea0284db79b
|
||||
#: ../../builders.rst:4
|
||||
msgid "Available builders"
|
||||
msgstr "<FILL HERE BY TARGET LANGUAGE>"
|
||||
|
||||
Another case, msgid is multi-line text and contains reStructuredText
|
||||
syntax:
|
||||
|
||||
.. code-block:: po
|
||||
|
||||
# 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."
|
||||
|
||||
Please be careful not to break reST notation.
|
||||
|
||||
|
||||
Update your po files by new pot files
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
If the document is updated, it is necessary to generate updated pot files
|
||||
and to apply differences to translated po files.
|
||||
In order to apply the updating difference of a pot file to po file,
|
||||
using :command:`sphinx-intl update` command.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ sphinx-intl update -p _build/locale
|
||||
|
||||
|
||||
Using Transifex service for team translation
|
||||
--------------------------------------------
|
||||
|
||||
.. TODO: why use transifex?
|
||||
|
||||
|
||||
#. Install `transifex-client`_
|
||||
|
||||
You need :command:`tx` command to upload resources (pot files).
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ pip install transifex-client
|
||||
|
||||
.. seealso:: `Transifex Client v0.8 — Transifex documentation`_
|
||||
|
||||
|
||||
#. 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 document, so you'd better include a
|
||||
version number in your project name.
|
||||
|
||||
For example:
|
||||
|
||||
:Project ID: ``sphinx-document-test_1_0``
|
||||
:Project URL: https://www.transifex.com/projects/p/sphinx-document-test_1_0/
|
||||
|
||||
|
||||
#. Create config files for tx command
|
||||
|
||||
This process will create ``.tx/config`` in the current directory, as
|
||||
well as ``~/.transifexrc`` file that includes auth information.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ tx init --user=<transifex-username> --pass=<transifex-password>
|
||||
Creating .tx folder...
|
||||
Transifex instance [https://www.transifex.com]:
|
||||
...
|
||||
Done.
|
||||
|
||||
#. Upload pot files to transifex service
|
||||
|
||||
Register pot files to ``.tx/config`` file:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ cd /your/document/root
|
||||
$ sphinx-intl update-txconfig-resources --pot-dir _build/locale \
|
||||
--transifex-project-name sphinx-document-test_1_0
|
||||
|
||||
and upload pot files:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ 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.
|
||||
|
||||
|
||||
#. Forward the translation on transifex
|
||||
|
||||
.. TODO: write this section
|
||||
|
||||
|
||||
#. Pull translated po files and make translated html
|
||||
|
||||
Get translated catalogs and build mo files (ex. for 'de'):
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ 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.
|
||||
|
||||
Build po files into mo and make html::
|
||||
|
||||
$ sphinx-intl build
|
||||
$ make -e SPHINXOPTS="-D language='de'" html
|
||||
|
||||
|
||||
That's all!
|
||||
|
||||
|
||||
.. tip:: Translating on local and Transifex
|
||||
|
||||
If you want to push all language's po files, you can be done by using
|
||||
:command:`tx push -t` command.
|
||||
Watch out! this operation overwrites translations in transifex.
|
||||
|
||||
In other words, if you have updated each in the service and local po files,
|
||||
it would take much time and effort to integrate them.
|
||||
|
||||
|
||||
|
||||
Contributing to Sphinx reference translation
|
||||
--------------------------------------------
|
||||
|
||||
The recommended way for new contributors to translate Sphinx reference
|
||||
is to join the translation team on Transifex.
|
||||
|
||||
There is `sphinx translation page`_ for Sphinx-1.2 document.
|
||||
|
||||
1. Login to transifex_ service.
|
||||
2. Go to `sphinx translation page`_.
|
||||
3. Click ``Request language`` and fill form.
|
||||
4. Wait acceptance by transifex sphinx translation maintainers.
|
||||
5. (after acceptance) translate on transifex.
|
||||
|
||||
|
||||
.. rubric:: Footnotes
|
||||
|
||||
.. [1] See the `GNU gettext utilites
|
||||
<http://www.gnu.org/software/gettext/manual/gettext.html#Introduction>`_
|
||||
for details on that software suite.
|
||||
.. [2] Because nobody expects the Spanish Inquisition!
|
||||
|
||||
|
||||
.. _`transifex-client`: https://pypi.python.org/pypi/transifex-client
|
||||
.. _`sphinx-intl`: https://pypi.python.org/pypi/sphinx-intl
|
||||
.. _Transifex: https://www.transifex.com/
|
||||
.. _`sphinx translation page`: https://www.transifex.com/projects/p/sphinx-doc-1_2_0/
|
||||
.. _`Transifex Client v0.8 — Transifex documentation`: http://help.transifex.com/features/client/index.html
|
||||
|
||||
@@ -1,265 +0,0 @@
|
||||
=================================
|
||||
Sphinx Document Translation Guide
|
||||
=================================
|
||||
|
||||
.. topic:: Abstract
|
||||
|
||||
This document describes the translation cycle of Sphinx-based document.
|
||||
For illustrative purpose, we use Sphinx document itself in this document.
|
||||
|
||||
The Sphinx document is included in the Sphinx code. It is managed by
|
||||
`Mercurial`_ and is hosted on `BitBucket`_.
|
||||
|
||||
|
||||
hg clone https://bitbucket.org/birkenfeld/sphinx
|
||||
cd sphinx/doc
|
||||
|
||||
|
||||
.. _`BitBucket`: http://bitbucket.org
|
||||
.. _`Mercurial`: http://mercurial.selenic.com/
|
||||
|
||||
|
||||
Translate the document
|
||||
======================
|
||||
|
||||
Getting Started
|
||||
---------------
|
||||
|
||||
This section describe to translate with Sphinx_ and `sphinx-intl`_.
|
||||
|
||||
#. Install `sphinx-intl`_ by :command:`pip install sphinx-intl` or
|
||||
:command:`easy_install sphinx-intl`.
|
||||
|
||||
#. Add configurations to your `conf.py`::
|
||||
|
||||
locale_dirs = ['locale/'] #path is example but recommended.
|
||||
gettext_compact = False #optional.
|
||||
|
||||
This case-study assumes that :confval:`locale_dirs` is set to 'locale/' and
|
||||
:confval:`gettext_compact` is set to `False` (the Sphinx document is
|
||||
already configured as such).
|
||||
|
||||
#. Extract document's translatable messages into pot files::
|
||||
|
||||
$ make gettext
|
||||
|
||||
As a result, many pot files are generated under ``_build/locale``
|
||||
directory.
|
||||
|
||||
#. Setup/Update your `locale_dir`::
|
||||
|
||||
$ sphinx-intl update -p _build/locale -l de -l ja
|
||||
|
||||
Done. You got these directories that contain po files:
|
||||
|
||||
* `./locale/de/LC_MESSAGES/`
|
||||
* `./locale/ja/LC_MESSAGES/`
|
||||
|
||||
#. Translate your po files under `./locale/<lang>/LC_MESSAGES/`.
|
||||
|
||||
#. Build mo files and make translated document.
|
||||
|
||||
You need :confval:`language` parameter in ``conf.py`` or you may also
|
||||
specify the parameter on the command line.
|
||||
|
||||
$ sphinx-intl build
|
||||
$ make -e SPHINXOPTS="-D language='ja'" html
|
||||
|
||||
|
||||
Congratulations!! You got the translated document in ``_build/html``
|
||||
directory.
|
||||
|
||||
|
||||
Translating
|
||||
------------
|
||||
|
||||
Translate po file under ``./locale/ja/LC_MESSAGES`` directory.
|
||||
The case of builders.po file for sphinx document:
|
||||
|
||||
.. code-block:: po
|
||||
|
||||
# a5600c3d2e3d48fc8c261ea0284db79b
|
||||
#: ../../builders.rst:4
|
||||
msgid "Available builders"
|
||||
msgstr "<FILL HERE BY TARGET LANGUAGE>"
|
||||
|
||||
Another case, msgid is multi-line text and contains reStructuredText
|
||||
syntax:
|
||||
|
||||
.. code-block:: po
|
||||
|
||||
# 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."
|
||||
|
||||
Please be careful not to break reST notation.
|
||||
|
||||
|
||||
Update your po files by new pot files
|
||||
--------------------------------------
|
||||
|
||||
If the document is updated, it is necessary to generate updated pot files
|
||||
and to apply differences to translated po files.
|
||||
In order to apply the updating difference of a pot file to po file,
|
||||
using :command:`sphinx-intl update` command.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ sphinx-intl update -p _build/locale
|
||||
|
||||
|
||||
Using Transifex service for team translation
|
||||
============================================
|
||||
|
||||
.. TODO: why use transifex?
|
||||
|
||||
|
||||
Make new translation project
|
||||
----------------------------
|
||||
|
||||
1. Create your transifex_ account (if not have) and login.
|
||||
|
||||
For example:
|
||||
|
||||
:Transifex UserName: <transifex-username>
|
||||
:Transifex Password: <transifex-password>
|
||||
|
||||
2. Create new project for your document.
|
||||
|
||||
Currently, transifex does not allow for a translation project to
|
||||
have more than one version of document, so you'd better include a
|
||||
version number in your project name.
|
||||
|
||||
For example:
|
||||
|
||||
:Project ID: ``sphinx-document-test_1_0``
|
||||
:Project URL: https://www.transifex.com/projects/p/sphinx-document-test_1_0/
|
||||
|
||||
|
||||
Install transifex client: tx
|
||||
-----------------------------
|
||||
|
||||
You need ``tx`` command to upload resources (pot files).
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ pip install transifex-client
|
||||
|
||||
|
||||
.. seealso:: `Transifex Client v0.8 — Transifex documentation`_
|
||||
|
||||
|
||||
Create config files for tx command
|
||||
----------------------------------
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ tx init --user=<transifex-username> --pass=<transifex-password>
|
||||
Creating .tx folder...
|
||||
Transifex instance [https://www.transifex.com]:
|
||||
Creating skeleton...
|
||||
Creating config file...
|
||||
No authentication data found.
|
||||
No entry found for host https://www.transifex.com. Creating...
|
||||
Updating /path/to/.transifexrc file...
|
||||
Done.
|
||||
|
||||
This process will create ``.tx/config`` in the current directory, as
|
||||
well as ``~/.transifexrc`` file that includes auth information.
|
||||
|
||||
|
||||
Register pot files in transifex
|
||||
-----------------------------------
|
||||
|
||||
Register pot files to ``.tx/config`` file:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ cd /your/document/root
|
||||
$ sphinx-intl update-txconfig-resources --pot-dir _build/locale --transifex-project-name sphinx-document-test_1_0
|
||||
|
||||
and upload pot files:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ 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.
|
||||
|
||||
|
||||
Forward the translation on transifex
|
||||
------------------------------------
|
||||
|
||||
...
|
||||
|
||||
|
||||
Pull translated po files and make translated html
|
||||
-------------------------------------------------
|
||||
|
||||
Get translated catalogs and build mo files (ex. for 'ja'):
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ cd /your/document/root
|
||||
$ tx pull -l ja
|
||||
Pulling translations for resource sphinx-document-test_1_0.builders (...)
|
||||
-> ja: locale/ja/LC_MESSAGES/builders.po
|
||||
...
|
||||
Done.
|
||||
|
||||
|
||||
Build po files into mo and make html::
|
||||
|
||||
$ sphinx-intl build
|
||||
$ make -e SPHINXOPTS="-D language='ja'" html
|
||||
|
||||
Done.
|
||||
|
||||
|
||||
Tranlating Tips
|
||||
================
|
||||
|
||||
* Translating local vs Transifex
|
||||
|
||||
If you want to push all language's po files, you can use `tx push -t`.
|
||||
(this operation overwrites translations in transifex.)
|
||||
|
||||
|
||||
* rebuild
|
||||
|
||||
:command:`make clean && make html`
|
||||
|
||||
|
||||
Contributing to Sphinx reference translation
|
||||
============================================
|
||||
|
||||
The recommended way for new contributors to translate Sphinx reference
|
||||
is to join the translation team on Transifex.
|
||||
|
||||
There is `sphinx translation page`_ for Sphinx-1.2 document.
|
||||
|
||||
1. login to transifex_ service.
|
||||
2. go to `sphinx translation page`_.
|
||||
3. push ``Request language`` and fill form.
|
||||
4. wait acceptance by transifex sphinx translation maintainers.
|
||||
5. (after acceptance) translate on transifex.
|
||||
|
||||
|
||||
|
||||
.. _`sphinx-intl`: https://pypi.python.org/sphinx-intl
|
||||
.. _Transifex: https://www.transifex.com/
|
||||
.. _msgmerge: http://www.gnu.org/software/gettext/manual/html_node/index.html
|
||||
.. _msgfmt: http://www.gnu.org/software/gettext/manual/html_node/index.html
|
||||
|
||||
.. _`sphinx translation page`: https://www.transifex.com/projects/p/sphinx-doc-1_2_0/
|
||||
|
||||
.. _`Transifex Client v0.8 — Transifex documentation`: http://help.transifex.com/features/client/index.html
|
||||
|
||||
Reference in New Issue
Block a user