Skip to main content
`Ctrl`+`K`

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