.. -*- rst -*-

I18N
====

We only had documentation in Japanese.  We start to support
I18N documentation by gettext based `Sphinx I18N feature`_.
We'll use English as base language and translate
English into other languages such as Japanese. We'll put
all documentations into doc/source/ and process them by
Sphinx.

.. _Sphinx I18N feature: https://www.sphinx-doc.org/en/master/usage/advanced/intl.html

But we still use Japanese in doc/source/ for now. We need to
translate Japanese documentation in doc/source/ into
English. We welcome to you help us by translating
documentation.

Translation flow
----------------

After doc/source/\*.txt are updated, we can start translation.

Here is a translation flow:

1. Install Sphinx, if it is not installed.
2. Clone Groonga repository.
3. Update ``.edit`` files
4. Edit ``.edit`` files
5. Update ``.po`` files.
6. Generate HTML files.
7. Confirm HTML output.
8. Repeat 3.-7. until you finish to translate.
9. Send your works to us!

Here are command lines to do the above flow. Following
sections describes details.

::

  # Please fork https://github.com/groonga/groonga on GitHub
  % git clone https://github.com/${YOUR_GITHUB_ACCOUNT}/groonga.git
  % ./autogen.sh
  % ./configure --enable-document
  % cd doc/locale/${LANGUAGE}/LC_MESSAGES # ${LANGUAGE} is language code such as 'ja'.
  % make # *.edit are updated
  % editor *.edit # translate *.edit # you can use your favorite editor
  % make # *.po are updated
  % cd ..
  % make html
  % browser html/index.html # confirm translation
  % git add LC_MESSAGES/*.po
  % git commit
  % git push

How to install Sphinx
---------------------

See the :doc:`introduction`.

How to clone Groonga repository
-------------------------------

First, please fork Groonga repository on GitHub. You
just access https://github.com/groonga/groonga and press
`Fork` button. Now you can clone your Groonga repository::

  % git clone https://github.com/${YOUR_GITHUB_ACCOUNT}/groonga.git

Then you need to configure your cloned repository::

  % cd groonga
  % ./autogen.sh
  % ./configure --enable-document

The above steps are just needed at the first setup.

If you have troubles on the above steps, you can use source
files available on https://packages.groonga.org/source/groonga/ .

How to update ``.edit`` files
-----------------------------

You can update ``.edit`` files by running ``make`` on
``doc/locale/${LANGUAGE}/LC_MESSAGES``. (Please replace
`${LANGUAGE}` with your language code such as 'ja'.)::

  % cd doc/locale/ja/LC_MESSAGES
  % make

How to edit ``.edit``
---------------------

Both of ``.edit`` files and ``.po`` files are `PO files <https://www.gnu.org/software/gettext/manual/html_node/PO-Files.html>`_. 
``.edit`` files are for editing and ``.po`` files are for versioning.

In order to edit ``.edit`` files, there are some tools to edit.
``.edit`` files are just text, so you can use your favorite editor.

Here is a list of editors specialized for editing ``.po`` files.
You can use these editors to edit ``.edit`` files because they are actually 
``.po`` files.

Emacs's po-mode_
  It is bundled in gettext.

Poedit_
  It is a ``.po`` editor and works on many platform.

gted
  It is also a ``.po`` editor and is implemented as Eclipse plugin.

.. _po-mode: http://www.gnu.org/s/hello/manual/gettext/PO-Mode.html
.. _Poedit: http://www.poedit.net/
.. _gted: http://www.gted.org/

How to update ``.po`` files
---------------------------

After editing ``.edit`` files, you can update ``.po`` files by running ``make`` on
``doc/locale/${LANGUAGE}/LC_MESSAGES``. (Please replace
`${LANGUAGE}` with your language code such as 'ja'.)

.. code-block ::

   % cd doc/locale/ja/LC_MESSAGES
   % make

How to generate HTML files
--------------------------

You can generate HTML files with updated ``.po`` files by
running `make html` on doc/locale/${LANGUAGE}. (Please
substitute `${LANGUAGE}` with your language code such as
'ja'.)::

  % cd doc/locale/ja/
  % make html

You can also generate HTML files for all languages by
running `make html` on doc/locale::

  % cd doc/locale
  % make html

.. note::

   .mo files are updated automatically by `make html`. So
   you don't care about .mo files.

How to confirm HTML output
--------------------------

HTML files are generated in
doc/locale/${LANGUAGE}/html/. (Please substitute
`${LANGUAGE}` with your language code such as 'ja'.) You can
confirm HTML output by your favorite browser::

  % firefox doc/locale/ja/html/index.html

How to send your works
----------------------

We can receive your works via pull request on GitHub or
E-mail attachment patch or ``.po`` files themselves.

How to send pull request
++++++++++++++++++++++++

Here are command lines to send pull request::

  % git add doc/locale/ja/LC_MESSAGES/*.po
  % git commit
  % git push

Now you can send pull request on GitHub. You just access
your repository page on GitHub and press `Pull Request`
button.

.. seealso:: `Help.GitHub - Sending pull requests <http://help.github.com/pull-requests/>`_.

How to send patch
+++++++++++++++++

Here are command lines to create patch::

  % git add doc/locale/ja/LC_MESSAGES/*.po
  % git commit
  % git format-patch origin/main

You can find 000X-YYY.patch files in the current
directory. Please send those files to us!

.. seealso:: :doc:`/community` describes our contact information.

How to send ``.po`` files
+++++++++++++++++++++++++

Please archive doc/locale/${LANGUAGE}/LC_MESSAGES/ (Please
substitute `${LANGUAGE}` with your language code such as
'ja'.) and send it to us! We extract and merge them to the
Groonga repository.

.. seealso:: :doc:`/community` describes our contact information.

How to add new language
-----------------------

Here are command lines to add new translation language::

  % cd doc/locale
  % make add LOCALE=${LANGUAGE} # specify your language code such as 'de'.

Please substitute `${LANGUAGE}` with your language code such
as 'ja'.

.. seealso:: `Codes for the Representation of Names of Languages <http://www.loc.gov/standards/iso639-2/php/English_list.php>`_.