12.2.2. 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.

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.

12.2.2.1. 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

12.2.2.2. How to install Sphinx#

See the Introduction.

12.2.2.3. How to clone Groonga repository#

First, please fork Groonga repository on GitHub. You just access 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/ .

12.2.2.4. 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

12.2.2.5. How to edit .edit#

Both of .edit files and .po files are PO files. .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.

12.2.2.6. 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’.)

% cd doc/locale/ja/LC_MESSAGES
% make

12.2.2.7. 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.

12.2.2.8. 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

12.2.2.9. How to send your works#

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

12.2.2.9.1. 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.

See also

Help.GitHub - Sending pull requests.

12.2.2.9.2. 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!

See also

Community describes our contact information.

12.2.2.9.3. 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.

See also

Community describes our contact information.

12.2.2.10. 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’.

See also

Codes for the Representation of Names of Languages.