Takayuki Shimizukawa avatar Takayuki Shimizukawa committed c43a499

update translation document

Comments (0)

Files changed (1)

doc/translationguide.rst

 
 
     hg clone https://bitbucket.org/birkenfeld/sphinx
+    cd sphinx/doc
 
 
 .. _`BitBucket`: http://bitbucket.org
 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
 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
 
    $ pip install transifex-client
 
+
 .. seealso:: `Transifex Client v0.8 &mdash; Transifex documentation`_
 
 
    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 $BASEDIR/sphinx/doc
+   $ 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)
    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
 -------------------------------------------------
 
 .. 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
 ================
 
 
 
 
+.. _`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
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.