diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/_templates/index.html | 86 | ||||
| -rw-r--r-- | doc/_templates/indexsidebar.html | 30 | ||||
| -rw-r--r-- | doc/conf.py | 4 | ||||
| -rw-r--r-- | doc/config.rst | 2 | ||||
| -rw-r--r-- | doc/contents.rst | 1 | ||||
| -rw-r--r-- | doc/ext/math.rst | 2 | ||||
| -rw-r--r-- | doc/install.rst | 154 | ||||
| -rw-r--r-- | doc/invocation.rst | 9 | ||||
| -rw-r--r-- | doc/rest.rst | 2 | ||||
| -rw-r--r-- | doc/translationguide.rst | 323 |
10 files changed, 468 insertions, 145 deletions
diff --git a/doc/_templates/index.html b/doc/_templates/index.html index cf276154..d1955cac 100644 --- a/doc/_templates/index.html +++ b/doc/_templates/index.html @@ -1,87 +1,87 @@ {% extends "layout.html" %} -{% set title = 'Overview' %} +{% set title = _('Overview') %} {% block body %} - <h1>Welcome</h1> + <h1>{{ _('Welcome') }}</h1> <div class="quotebar"> - <p><em>What users say:</em></p> - <p>“Cheers for a great tool that actually makes programmers <b>want</b> - to write documentation!”</p> + <p><em>{%trans%}What users say:{%endtrans%}</em></p> + <p>{%trans%}“Cheers for a great tool that actually makes programmers <b>want</b> + to write documentation!”{%endtrans%}</p> </div> - <p> + <p>{%trans%} Sphinx is a tool that makes it easy to create intelligent and beautiful - documentation, written by Georg Brandl and licensed under the BSD license.</p> - <p>It was originally created for <a href="http://docs.python.org/">the + documentation, written by Georg Brandl and licensed under the BSD license.{%endtrans%}</p> + <p>{%trans%}It was originally created for <a href="http://docs.python.org/">the new Python documentation</a>, and it has excellent facilities for the documentation of Python projects, but C/C++ is already supported as well, and it is planned to add special support for other languages as well. Of course, this site is also created from reStructuredText sources using - Sphinx! The following features should be highlighted: + Sphinx! The following features should be highlighted:{%endtrans%} </p> <ul> - <li><b>Output formats:</b> HTML (including Windows HTML Help), LaTeX (for - printable PDF versions), Texinfo, manual pages, plain text</li> - <li><b>Extensive cross-references:</b> semantic markup and automatic links + <li>{%trans%}<b>Output formats:</b> HTML (including Windows HTML Help), LaTeX (for + printable PDF versions), Texinfo, manual pages, plain text{%endtrans%}</li> + <li>{%trans%}<b>Extensive cross-references:</b> semantic markup and automatic links for functions, classes, citations, glossary terms and similar pieces of - information</li> - <li><b>Hierarchical structure:</b> easy definition of a document tree, with - automatic links to siblings, parents and children</li> - <li><b>Automatic indices:</b> general index as well as a language-specific - module indices</li> - <li><b>Code handling:</b> automatic highlighting using the <a - href="http://pygments.org">Pygments</a> highlighter</li> - <li><b>Extensions:</b> automatic testing of code snippets, inclusion of + information{%endtrans%}</li> + <li>{%trans%}<b>Hierarchical structure:</b> easy definition of a document tree, with + automatic links to siblings, parents and children{%endtrans%}</li> + <li>{%trans%}<b>Automatic indices:</b> general index as well as a language-specific + module indices{%endtrans%}</li> + <li>{%trans%}<b>Code handling:</b> automatic highlighting using the <a + href="http://pygments.org">Pygments</a> highlighter{%endtrans%}</li> + <li>{%trans path=pathto('extensions')%}<b>Extensions:</b> automatic testing of code snippets, inclusion of docstrings from Python modules (API docs), and - <a href="{{ pathto('extensions') }}#builtin-sphinx-extensions">more</a></li> + <a href="{{ path }}#builtin-sphinx-extensions">more</a>{%endtrans%}</li> </ul> - <p> + <p>{%trans%} Sphinx uses <a href="http://docutils.sf.net/rst.html">reStructuredText</a> as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating - suite, the <a href="http://docutils.sf.net/">Docutils</a>. + suite, the <a href="http://docutils.sf.net/">Docutils</a>.{%endtrans%} </p> - <h2 style="margin-bottom: 0">Documentation</h2> + <h2 style="margin-bottom: 0">{%trans%}Documentation{%endtrans%}</h2> <table class="contentstable" align="center" style="margin-left: 30px"><tr> <td width="50%"> - <p class="biglink"><a class="biglink" href="{{ pathto("tutorial") }}">First steps with Sphinx</a><br/> - <span class="linkdescr">overview of basic tasks</span></p> - <p class="biglink"><a class="biglink" href="{{ pathto("contents") }}">Contents</a><br/> - <span class="linkdescr">for a complete overview</span></p> + <p class="biglink"><a class="biglink" href="{{ pathto("tutorial") }}">{%trans%}First steps with Sphinx{%endtrans%}</a><br/> + <span class="linkdescr">{%trans%}overview of basic tasks{%endtrans%}</span></p> + <p class="biglink"><a class="biglink" href="{{ pathto("contents") }}">{%trans%}Contents{%endtrans%}</a><br/> + <span class="linkdescr">{%trans%}for a complete overview{%endtrans%}</span></p> </td><td width="50%"> - <p class="biglink"><a class="biglink" href="{{ pathto("search") }}">Search page</a><br/> - <span class="linkdescr">search the documentation</span></p> - <p class="biglink"><a class="biglink" href="{{ pathto("genindex") }}">General Index</a><br/> - <span class="linkdescr">all functions, classes, terms</span></p> + <p class="biglink"><a class="biglink" href="{{ pathto("search") }}">{%trans%}Search page{%endtrans%}</a><br/> + <span class="linkdescr">{%trans%}search the documentation{%endtrans%}</span></p> + <p class="biglink"><a class="biglink" href="{{ pathto("genindex") }}">{%trans%}General Index{%endtrans%}</a><br/> + <span class="linkdescr">{%trans%}all functions, classes, terms{%endtrans%}</span></p> </td></tr> </table> - <p> + <p>{%trans%} You can also download PDF versions of the Sphinx documentation: a <a href="http://sphinx-doc.org/sphinx.pdf">version</a> generated from the LaTeX Sphinx produces, and a <a href="http://sphinx-doc.org/sphinx-rst2pdf.pdf">version</a> generated - by rst2pdf. + by rst2pdf.{%endtrans%} </p> - <h2>Examples</h2> - <p>Links to documentation generated with Sphinx can be found on the - <a href="{{ pathto("examples") }}">Projects using Sphinx</a> page. + <h2>{%trans%}Examples{%endtrans%}</h2> + <p>{%trans path=pathto("examples")%}Links to documentation generated with Sphinx can be found on the + <a href="{{ path }}">Projects using Sphinx</a> page.{%endtrans%} </p> - <p> + <p>{%trans%} For examples of how Sphinx source files look, use the “Show source” links on all pages of the documentation apart from this - welcome page. + welcome page.{%endtrans%} </p> - <p>You may also be interested in the very nice + <p>{%trans%}You may also be interested in the very nice <a href="http://matplotlib.sourceforge.net/sampledoc/">tutorial</a> on how to create a customized documentation using Sphinx written by the matplotlib - developers.</p> + developers.{%endtrans%}</p> - <p>There is a <a href="http://sphinx-users.jp/doc10/">Japanese translation</a> - of this documentation, thanks to Yoshiki Shibukawa.</p> + <p>{%trans%}There is a <a href="http://sphinx-users.jp/doc10/">Japanese translation</a> + of this documentation, thanks to Yoshiki Shibukawa.{%endtrans%}</p> {% endblock %} diff --git a/doc/_templates/indexsidebar.html b/doc/_templates/indexsidebar.html index f9aa2abf..7805b942 100644 --- a/doc/_templates/indexsidebar.html +++ b/doc/_templates/indexsidebar.html @@ -1,32 +1,32 @@ <p class="logo">A <a href="http://pocoo.org/"> - <img src="{{ pathto("_static/pocoo.png", 1) }}" /></a> project</a></p> + <img src="{{ pathto("_static/pocoo.png", 1) }}" /></a> {%trans%}project{%endtrans%}</a></p> <h3>Download</h3> {% if version.endswith('(hg)') %} -<p>This documentation is for version <b>{{ version }}</b>, which is - not released yet.</p> -<p>You can use it from the +<p>{%trans%}This documentation is for version <b>{{ version }}</b>, which is + not released yet.{%endtrans%}</p> +<p>{%trans%}You can use it from the <a href="http://bitbucket.org/birkenfeld/sphinx/">Mercurial repo</a> or look for released versions in the <a href="http://pypi.python.org/pypi/Sphinx">Python - Package Index</a>.</p> + Package Index</a>.{%endtrans%}</p> {% else %} -<p>Current version: <b>{{ version }}</b></p> -<p>Get Sphinx from the <a href="http://pypi.python.org/pypi/Sphinx">Python Package -Index</a>, or install it with:</p> +<p>{%trans%}Current version: <b>{{ version }}</b>{%endtrans%}</p> +<p>{%trans%}Get Sphinx from the <a href="http://pypi.python.org/pypi/Sphinx">Python Package +Index</a>, or install it with:{%endtrans%}</p> <pre>easy_install -U Sphinx</pre> -<p>Latest <a href="http://sphinx-doc.org/latest/">development version docs</a> -are also available.</p> +<p>{%trans%}Latest <a href="http://sphinx-doc.org/latest/">development version docs</a> +are also available.{%endtrans%}</p> {% endif %} -<h3>Questions? Suggestions?</h3> +<h3>{%trans%}Questions? Suggestions?{%endtrans%}</h3> -<p>Join the <a href="http://groups.google.com/group/sphinx-users">Google group</a>:</p> +<p>{%trans%}Join the <a href="http://groups.google.com/group/sphinx-users">Google group</a>:{%endtrans%}</p> <form action="http://groups.google.com/group/sphinx-users/boxsubscribe" style="padding-left: 0.5em"> <input type="text" name="email" value="your@email" style="font-size: 90%; width: 120px" onfocus="$(this).val('');"/> <input type="submit" name="sub" value="Subscribe" style="font-size: 90%; width: 70px"/> </form> -<p>or come to the <tt>#pocoo</tt> channel on FreeNode.</p> -<p>You can also open an issue at the - <a href="http://www.bitbucket.org/birkenfeld/sphinx/issues/">tracker</a>.</p> +<p>{%trans%}or come to the <tt>#pocoo</tt> channel on FreeNode.{%endtrans%}</p> +<p>{%trans%}You can also open an issue at the + <a href="http://www.bitbucket.org/birkenfeld/sphinx/issues/">tracker</a>.{%endtrans%}</p> diff --git a/doc/conf.py b/doc/conf.py index 8dc1e2fb..6e792b6a 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -83,6 +83,10 @@ texinfo_documents = [ # the mapping: intersphinx_mapping = {'python': ('http://docs.python.org/dev', None)} +# Sphinx document translation with sphinx gettext feature uses these settings: +locale_dirs = ['locale/'] +gettext_compact = False + # -- Extension interface ------------------------------------------------------- diff --git a/doc/config.rst b/doc/config.rst index 2b8d33f2..6261e293 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -963,6 +963,8 @@ the `Dublin Core metadata <http://dublincore.org/>`_. :confval:`html_use_index` option but can be set independently for epub creation. + .. versionadded:: 1.2 + .. _latex-options: Options for LaTeX output diff --git a/doc/contents.rst b/doc/contents.rst index 5e0ae6c1..044c2d64 100644 --- a/doc/contents.rst +++ b/doc/contents.rst @@ -23,6 +23,7 @@ Sphinx documentation contents faq glossary devguide + translationguide changes examples diff --git a/doc/ext/math.rst b/doc/ext/math.rst index 91376d15..8b2924c7 100644 --- a/doc/ext/math.rst +++ b/doc/ext/math.rst @@ -196,7 +196,7 @@ Sphinx. MathJax. The default is the ``http://`` URL that loads the JS files from the `MathJax - CDN <http://www.mathjax.org/docs/1.1/start.html>`_. If you want MathJax to + CDN <http://docs.mathjax.org/en/latest/start.html>`_. If you want MathJax to be available offline, you have to donwload it and set this value to a different path. diff --git a/doc/install.rst b/doc/install.rst index d4457899..b1e0e5b6 100644 --- a/doc/install.rst +++ b/doc/install.rst @@ -1,11 +1,12 @@ :orphan: Installing Sphinx -================== +================= -Sphinx is written by Python, you need to install Python and Sphinx. +Since Sphinx is written in the Python language, you need to install Python +(the required version is at least 2.5) and Sphinx. -Sphinx package is available as a package on the `Python Package Index +Sphinx packages are available on the `Python Package Index <http://pypi.python.org/pypi/Sphinx>`_. You can also download a snapshot from the Mercurial development repository: @@ -14,7 +15,7 @@ You can also download a snapshot from the Mercurial development repository: file or * as a `.zip <https://bitbucket.org/birkenfeld/sphinx/get/default.zip>`_ file -There is introductions for each environments: +There are introductions for several environments: .. contents:: :depth: 1 @@ -22,145 +23,128 @@ There is introductions for each environments: :backlinks: none -Install by your own --------------------- - -If you use system installed Python or build your own Python, you can -use that python to install Sphinx. The actual command list is same as -these install. - -* `Install easy_install command`_ -* `Install Sphinx`_ - - Debian/Ubuntu: Install Sphinx using packaging system ------------------------------------------------------ +---------------------------------------------------- You may install using this command if you use Debian/Ubuntu. .. code-block:: bash - $ aptitude install python-sphinx + $ apt-get install python-sphinx + + +Other Linux distributions +------------------------- + +Most Linux distributions have Sphinx in their package repositories. Usually the +package is called "python-sphinx", "python-Sphinx" or "sphinx". Be aware that +there are two other packages with "sphinx" in their name: a speech recognition +toolkit (CMU Sphinx) and a full-text search database (Sphinx search). Mac OS X: Install Sphinx using MacPorts ----------------------------------------- +--------------------------------------- -If you use Mac OS X `MacPorts <http://www.macports.org/>`_ , use this -command to install all software. +If you use Mac OS X `MacPorts <http://www.macports.org/>`_, use this command to +install all necessary software. .. code-block:: bash $ sudo port install py27-sphinx -However, the execution path is not added, use select command to use -Python2.7 as default. +To set up the executable paths, use the ``port select`` command: .. code-block:: bash $ sudo port select --set python python27 $ sudo port select --set sphinx py27-sphinx -Type :command:`which sphinx-quickstart` to check the installation. +Type :command:`which sphinx-quickstart` to check if the installation was +successful. Windows: Install Python and Sphinx ------------------------------------ +---------------------------------- -Intall Python +Install Python ^^^^^^^^^^^^^^ -Almost every Windows user do not have Python, we begin Python -installation. If you already install python, please skip this section. +Most Windows users do not have Python, so we begin with the installation of +Python itself. If you have already installed Python, please skip this section. -Go to http://python.org . This site is a headquarter of the -Python. Look at Left sidebar and "Quick Links", Click "Windows -Installer" to download. +Go to http://python.org, the main download site for Python. Look at the left +sidebar and under "Quick Links", click "Windows Installer" to download. .. image:: pythonorg.png .. note:: - Currently, Python has two version, 2.X and 3.X. Sphinx-1.2 can - run under Python-2.5, 2.6, 2.7, 3.1, 3.2, 3.3. - You may get some advice from ML or other places. + Currently, Python offers two major versions, 2.x and 3.x. Sphinx 1.2 can run + under Python 2.5 to 2.7 and 3.1 to 3.3, with the recommended version being + 2.7. This chapter assumes you have installed Python 2.7. - This chapter assumes Python-2.7. - - -Follow the normal Windows installer, the Python install will be completed. +Follow the Windows installer for Python. .. image:: installpython.jpg -After installation, you have better to add PATH to the Environment -Variable in order to run Python from Command Prompt. - -* Right-Click the My Computer Icon and open Property Dialog -* Click Environment Variable button under detail tab -* Edit and add the path to the system variables PATH - -Add these variables. This is for Python-2.7. If you use another version -of Python, change the "27" number. Add these pathes separeted by ";". +After installation, you better add the Python executable directories to the +environment variable ``PATH`` in order to run Python and package commands such +as ``sphinx-build`` easily from the Command Prompt. -.. list-table:: Adding PATH - :widths: 10 40 - :header-rows: 1 +* Right-click the "My Computer" icon and choose "Properties" +* Click the "Environment Variables" button under the "Advanced" tab - * - PATH - - description - * - C:\\Python27 - - Folder which includes Python Command - * - C:\\Python27\\Scripts - - Folder which includes easy_install (described later) or sphinx commands +* If "Path" (or "PATH") is already an entry in the "System variables" list, edit + it. If it is not present, add a new variable called "PATH". -Run **Command Prompt** or enter ``cmd`` to the "search program and -files" text box. After command prompt window appear, type -``python[Enter]``. If you can get installed python version and prompt -about ``>>>``, the Python installation is succeeded. Enter ``Ctrl+Z`` -key to quit. +* Add these paths, separating entries by ";": + - ``C:\Python27`` -- this folder contains the main Python executable + - ``C:\Python27\Scripts`` -- this folder will contain executables added by + Python packages installed with easy_install (see below) -Install easy_install command -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + This is for Python 2.7. If you use another version of + Python or installed to a non-default location, change the digits "27" + accordingly. -Python has very useful :command:`easy_install` command which install 3rd -party library. +* Now run the **Command Prompt**. After command prompt window appear, type + ``python`` and Enter. If the Python installation was successful, the + installed Python version is printed, and you are greeted by the prompt + ``>>>``. Type ``Ctrl+Z`` and Enter to quit. -* http://pypi.python.org/pypi/distribute -easy_install downloads and install software which you want to need by only -one command. +Install the easy_install command +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Python has a very useful :command:`easy_install` command which can download and +install 3rd-party libraries with a single command. This is provided by the +"distribute" project: http://pypi.python.org/pypi/distribute. -Save http://distribute.org/distribute_setup.py link by Right-click. -Some browsers can download just open the URL. -If you can read the file iteslf, calm down, Right-click and choose "Save". - -After download, invoke command prompt, go to the distribute_setup.py saved -directory and run this command: +To install distribute, download http://distribute.org/distribute_setup.py and +save it somewhere. After download, invoke the command prompt, go to the +directory with distribute_setup.py and run this command: .. code-block:: bat C:\> python distribute_setup.py -Now :command:`easy_insall` command is installed. OK, Let's go to the Sphinx -install! +Now distribute and its :command:`easy_install` command is installed. From there +we can go to the Sphinx install. -Install Sphinx -^^^^^^^^^^^^^^^ +Installing Sphinx with easy_install +----------------------------------- -If you finshed easy_install install, for the rest is just a moment. -Type this line. +If you finished the installation of distribute, type this line in the command +prompt: .. code-block:: bat C:\> easy_install sphinx -After installation, type :command:`sphinx-quickstart` on the command -prompt. If you get interactive messages which starts with -``Welcome to the Sphinx <version> quickstart utility.``, -installation is succeeded. Quit by hitting ``Ctrl+C``. - -That it. Install is over. Let's go to :doc:`tutorial` to make Sphinx project. +After installation, type :command:`sphinx-build` on the command prompt. If +everything worked fine, you will get a Sphinx version number and a list of +options for this command. +That it. Installation is over. Head to :doc:`tutorial` to make a Sphinx +project. diff --git a/doc/invocation.rst b/doc/invocation.rst index 4cfa4843..c6125ecc 100644 --- a/doc/invocation.rst +++ b/doc/invocation.rst @@ -96,6 +96,15 @@ The :program:`sphinx-build` script has several options: the build directory; with this option you can select a different cache directory (the doctrees can be shared between all builders). +.. option:: -j N + + Distribute the build over *N* processes in parallel, to make building on + multiprocessor machines more effective. Note that not all parts and not all + builders of Sphinx can be parallelized. + + .. versionadded:: 1.2 + This option should be considered *experimental*. + .. option:: -c path Don't look for the :file:`conf.py` in the source directory, but use the given diff --git a/doc/rest.rst b/doc/rest.rst index ccf51c66..ccfdf11d 100644 --- a/doc/rest.rst +++ b/doc/rest.rst @@ -50,7 +50,7 @@ Be aware of some restrictions of this markup: These restrictions may be lifted in future versions of the docutils. -reST also allows for custom "interpreted text roles"', which signify that the +reST also allows for custom "interpreted text roles", which signify that the enclosed text should be interpreted in a specific way. Sphinx uses this to provide semantic markup and cross-referencing of identifiers, as described in the appropriate section. The general syntax is ``:rolename:`content```. diff --git a/doc/translationguide.rst b/doc/translationguide.rst new file mode 100644 index 00000000..87fe3c92 --- /dev/null +++ b/doc/translationguide.rst @@ -0,0 +1,323 @@ +=================================
+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
+
+
+.. _`BitBucket`: http://bitbucket.org
+.. _`Mercurial`: http://mercurial.selenic.com/
+
+
+Translate the document
+======================
+
+Getting Started
+---------------
+
+These are the basic steps needed to start translating the Sphinx document.
+
+
+#. Clone the sphinx repository to your machine.
+
+ .. 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
+
+ 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.
+
+ .. code-block:: bash
+
+ 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.
+
+ .. code-block:: bash
+
+ mkdir locale
+ cp -R _build/locale locale/pot
+
+
+#. Generate po files from pot files.
+
+ 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
+
+ mkdir -p locale/ja/LC_MESSAGES
+ cp -R locale/pot/* ja/LC_MESSAGES
+ 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
+
+ # 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
+ $ 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.
+
+.. code-block:: bash
+
+ $ msgmerge -U locale/pot/builders.pot locale/ja/LC_MESSAGES/builders.po
+ ........... done.
+
+
+.. TODO: write loop command
+
+
+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 /home/ubuntu/.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
+-----------------------------------
+
+.. 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)
+ Resource does not exist. Creating...
+ ...
+ 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
+-------------------------------------------------
+
+Get translated catalogs and build mo files (ex. for 'ja'):
+
+.. code-block:: bash
+
+ $ cd $BASEDIR/sphinx/doc
+ $ tx pull -l ja
+ Pulling translations for resource sphinx-document-test_1_0.builders (source: locale/pot/builders.pot)
+ -> ja: locale/ja/LC_MESSAGES/builders.po
+ ...
+ Done.
+
+
+convert po files into mo::
+
+ $ msgfmt ....
+
+
+Build html (ex. for 'ja')::
+
+ $ 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.
+
+
+
+.. _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
+
|