update translation document

doc/translationguide.rst

@@ -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,66 +25,56 @@ 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
+      locale_dirs = ['locale/']   #path is example but recommended.
-
+      gettext_compact = False     #optional.
-      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
 
    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/``
+   directory.
-   then ``locale/pot`` directory is proper location for pot files.
 
-   .. code-block:: bash
+#. Setup/Update your `locale_dir`::
 
-      mkdir locale
+      $ sphinx-intl update -p _build/locale -l de -l ja
-      cp -R _build/locale locale/pot
+
+   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
 
 
-#. Generate po files from pot files.
+Congratulations!! You got the translated document in ``_build/html``
+directory.
 
-   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:
 
-   .. code-block:: bash
+Translating
+------------
 
-      mkdir -p locale/ja/LC_MESSAGES
+Translate po file under ``./locale/ja/LC_MESSAGES`` directory.
-      cp -R locale/pot/* ja/LC_MESSAGES
+The case of builders.po file for sphinx document:
-      cd locale/ja/LC_MESSAGES
-
-      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
 
@@ -109,63 +100,17 @@ These are the basic steps needed to start translating the Sphinx document.
 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
-      $ make -e SPHINXOPTS="-D language='ja'" html
-
-   Congratulations!! You got the translated document in ``_build/html``
-   directory.
-
-
 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
+   $ sphinx-intl update -p _build/locale
-   ........... done.
-
-
-.. TODO: write loop command
 
 
 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 &mdash; 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::
+Build po files into mo and make html::
-
-   $ msgfmt ....
-
-
-Build html (ex. for 'ja')::
 
+   $ 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