mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
update translation document
This commit is contained in:
Takayuki Shimizukawa
parent
36157e7cb8
commit
3b9ae95d01
@ -12,6 +12,7 @@ The Sphinx document is included in the Sphinx code. It is managed by
|
||||
|
||||
|
||||
hg clone https://bitbucket.org/birkenfeld/sphinx
|
||||
cd sphinx/doc
|
||||
|
||||
|
||||
.. _`BitBucket`: http://bitbucket.org
|
||||
@ -24,131 +25,79 @@ Translate the document
|
||||
Getting Started
|
||||
---------------
|
||||
|
||||
These are the basic steps needed to start translating the Sphinx document.
|
||||
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`.
|
||||
|
||||
#. Clone the sphinx repository to your machine.
|
||||
#. Add configurations to your `conf.py`::
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
hg clone https://bitbucket.org/birkenfeld/sphinx
|
||||
cd sphinx/doc
|
||||
|
||||
|
||||
#. Add below settings to sphinx document's conf.py if not exists.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
locale_dirs = ['locale/'] #for example
|
||||
gettext_compact = False #optional
|
||||
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).
|
||||
|
||||
#. Generate pot files from the document.
|
||||
#. Extract document's translatable messages into pot files::
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
make gettext
|
||||
...
|
||||
$ make gettext
|
||||
|
||||
As a result, many pot files are generated under ``_build/locale``
|
||||
directory. By the way, :confval:`locale_dirs` is set to ``locale/``
|
||||
then ``locale/pot`` directory is proper location for pot files.
|
||||
directory.
|
||||
|
||||
.. code-block:: bash
|
||||
#. Setup/Update your `locale_dir`::
|
||||
|
||||
mkdir locale
|
||||
cp -R _build/locale locale/pot
|
||||
$ sphinx-intl update -p _build/locale -l de -l ja
|
||||
|
||||
Done. You got these directories that contain po files:
|
||||
|
||||
#. Generate po files from pot files.
|
||||
* `./locale/de/LC_MESSAGES/`
|
||||
* `./locale/ja/LC_MESSAGES/`
|
||||
|
||||
Sphinx expects that translated po files are under
|
||||
``locale/<lang>/LC_MESSAGES/`` directory. For Japanese, you need
|
||||
``locale/ja/LC_MESSAGE/`` directory and po files under the
|
||||
directory. The po files can be copied and renamed from pot files:
|
||||
#. Translate your po files under `./locale/<lang>/LC_MESSAGES/`.
|
||||
|
||||
.. code-block:: bash
|
||||
#. Build mo files and make translated document.
|
||||
|
||||
mkdir -p locale/ja/LC_MESSAGES
|
||||
cp -R locale/pot/* ja/LC_MESSAGES
|
||||
cd locale/ja/LC_MESSAGES
|
||||
You need :confval:`language` parameter in ``conf.py`` or you may also
|
||||
specify the parameter on the command line.
|
||||
|
||||
find . -name "*.pot" -type f -print0 |while read -r -d '' file; do
|
||||
mv "$file" "${file%.*}.po";
|
||||
done
|
||||
|
||||
#. Translating!
|
||||
|
||||
Translate po file under ``sphinx/doc/locale/ja/LC_MESSAGES`` directory.
|
||||
The case of builders.po:
|
||||
|
||||
.. 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.
|
||||
|
||||
|
||||
#. Compile po files into mo.
|
||||
|
||||
You need msgfmt_ command line tool to compile po files. For example,
|
||||
the case of debian, you can install the command by this command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo apt-get install gettext
|
||||
|
||||
and do compile each po files:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cd sphinx/doc/locale/ja/LC_MESSAGES
|
||||
msgfmt builders.po -o builders.mo
|
||||
...
|
||||
|
||||
in one line:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
find . -name "*.po" -type f -print0 | while read -r -d '' file; do \
|
||||
msgfmt "$file" -o "${file%.*}.mo"; \
|
||||
done
|
||||
|
||||
|
||||
|
||||
#. Make translated html (or other format).
|
||||
|
||||
Now you are ready to make the translated document by the
|
||||
:command:`make html` command. You need :confval:`language` parameter in
|
||||
``conf.py`` or you may also specify the parameter on the command line.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ cd sphinx/doc
|
||||
$ sphinx-intl build
|
||||
$ make -e SPHINXOPTS="-D language='ja'" html
|
||||
|
||||
Congratulations!! You got the translated document in ``_build/html``
|
||||
directory.
|
||||
|
||||
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
|
||||
@ -157,15 +106,11 @@ 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 msgmerge_ command.
|
||||
using :command:`sphinx-intl update` command.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ msgmerge -U locale/pot/builders.pot locale/ja/LC_MESSAGES/builders.po
|
||||
........... done.
|
||||
|
||||
|
||||
.. TODO: write loop command
|
||||
$ sphinx-intl update -p _build/locale
|
||||
|
||||
|
||||
Using Transifex service for team translation
|
||||
@ -205,6 +150,7 @@ You need ``tx`` command to upload resources (pot files).
|
||||
|
||||
$ pip install transifex-client
|
||||
|
||||
|
||||
.. seealso:: `Transifex Client v0.8 — Transifex documentation`_
|
||||
|
||||
|
||||
@ -220,22 +166,27 @@ Create config files for tx command
|
||||
Creating config file...
|
||||
No authentication data found.
|
||||
No entry found for host https://www.transifex.com. Creating...
|
||||
Updating /home/ubuntu/.transifexrc file...
|
||||
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
|
||||
|
||||
$ cd $BASEDIR/sphinx/doc
|
||||
$ tx push -s
|
||||
Pushing translations for resource sphinx-document-test_1_0.builders:
|
||||
Pushing source file (locale/pot/builders.pot)
|
||||
@ -244,16 +195,11 @@ Register pot files in transifex
|
||||
Done.
|
||||
|
||||
|
||||
.. note::
|
||||
|
||||
there is tx command wrapper tool to easier.
|
||||
|
||||
https://bitbucket.org/shimizukawa/sphinx-transifex
|
||||
|
||||
|
||||
Forward the translation on transifex
|
||||
------------------------------------
|
||||
|
||||
...
|
||||
|
||||
|
||||
Pull translated po files and make translated html
|
||||
-------------------------------------------------
|
||||
@ -262,27 +208,22 @@ Get translated catalogs and build mo files (ex. for 'ja'):
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ cd $BASEDIR/sphinx/doc
|
||||
$ cd /your/document/root
|
||||
$ tx pull -l ja
|
||||
Pulling translations for resource sphinx-document-test_1_0.builders (source: locale/pot/builders.pot)
|
||||
Pulling translations for resource sphinx-document-test_1_0.builders (...)
|
||||
-> ja: locale/ja/LC_MESSAGES/builders.po
|
||||
...
|
||||
Done.
|
||||
|
||||
|
||||
convert po files into mo::
|
||||
|
||||
$ msgfmt ....
|
||||
|
||||
|
||||
Build html (ex. for 'ja')::
|
||||
Build po files into mo and make html::
|
||||
|
||||
$ sphinx-intl build
|
||||
$ make -e SPHINXOPTS="-D language='ja'" html
|
||||
|
||||
Done.
|
||||
|
||||
|
||||
|
||||
Tranlating Tips
|
||||
================
|
||||
|
||||
@ -313,6 +254,7 @@ There is `sphinx translation page`_ for Sphinx-1.2 document.
|
||||
|
||||
|
||||
|
||||
.. _`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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user