TRANSLATING.md

Rust by Example translation guidelines

Please see the CONTRIBUTING.md file for general contribution guidelines. This file describes about the translation workflow.

Translation workflow

Preparation

RBE uses mdbook-i18n-helpers as a translation framework. The following tools are required.

• GNU gettext utilities ( msgmerge and msgcat )
• mdbook-i18n-helpers ( cargo install mdbook-i18n-helpers )

Creating and Updating Translations

Please see the mdbook-i18n-helpers USAGE file for the detailed usage of mdbook-i18n-helpers. The summarized command list is below:

Generating a message template

The generated message templete po/messages.pot is required to create or update translations.

MDBOOK_OUTPUT='{"xgettext": {"pot-file": "messages.pot"}}' \
  mdbook build -d po

Creating a new translation resource

xx is ISO 639 language code.

msginit -i po/messages.pot -l xx -o po/xx.po

Updating the exising translation resource

msgmerge --update po/xx.po po/messages.pot

Editing translation resources

After generating a translation resource po/xx.po, you can write translation messages in msgstr entry of po/xx.po. To build a translated book, the following command can be used.

MDBOOK_BOOK__LANGUAGE=xx mdbook build
MDBOOK_BOOK__LANGUAGE=xx mdbook serve

Add a language entry

Please add a language entry in .github/workflows/rbe.yml and theme/index.hbs like below:

• rbe.yml

env:
  # Update the language picker in index.hbs to link new languages.
  LANGUAGES: xx yy zz

• index.hbs

<ul id="language-list" class="theme-popup" aria-label="Languages" role="menu">
  <li role="none"><button role="menuitem" class="theme">
      <a id="en">English</a>
  </button></li>
  <li role="none"><button role="menuitem" class="theme">
      <a id="xx">XX language</a>
  </button></li>
  <li role="none"><button role="menuitem" class="theme">
      <a id="yy">YY language</a>
  </button></li>
  <li role="none"><button role="menuitem" class="theme">
      <a id="zz">ZZ language</a>
  </button></li>
</ul>