rbot uses ruby-gettext for translation of messages, which exposes an interface similar to GNU GetText to both developers and translators.

For Developers

Translatable strings

For i18n, strings such as replies, help messages, and user-oriented error messages should be translated into the user's language.

Marking strings as translatable

In the source code, translatable strings generally need to be marked with the _ method, for example, _('This message should be translated'). There is also an n_ method designed for messages with singular and plural forms.

There is much existing code which still haven't been marked for gettext. This is usually a tedious process, but the utility texter (git) can reduce some of the work. Note that it is experimental software, you should carefully examine the processed output file, and read the BUGS section in documentation.

Update po files

After source code is marked, the tool rgettext needs to be run to collect translatable strings into po files, which translators work on. Rbot's Rakefile helps with this task:

$ rake updatepo

If you commit to vcs, it's recommended to update po before each commit where you have edited, added or removed translatable strings.

Strings with embedded code

Unfortunately ruby-gettext cannot work strings like "The sum of #{a} and #{b} is #{a + b}". You'll need to rewrite translatable strings into this form:

_("The sum of %{a} and %{b} is %{sum}") % {:a => a, :b => b, :sum => a + b}

Note that ruby-gettext extends String#% to make it take a hash argument. This makes it easier for translators to understand the strings, and to translate them into languages that may have different word order patterns from English.

Avoid string concatenation

Using string concatenation, for example

str = "The file is"
str << " not " unless found?
str << "found."
str

can make messages difficult to translate into other languages. Always try to write whole messages as strings, like

if found? 
  _("The file is found.")
else
  _("The file is not found.")
end

Follow GNU Gettext Manual's tips on preparing strings.

For Translators

To translate rbot you need to be able to work with gettext message catalog (PO) files. A few editors for PO files are linked here, but a plain text editor is enough.

Specific Notes for ruby-gettext and rbot

Some messages contain code like %{word}. These are placeholders where strings are substituted when rbot runs. You should ensure that the placeholder is unmodified in the translated message, in its appropriate place. For example:

msg-id "The sum of %{a} and %{b} is %{c}"
msg-str "%{a} + %{b} = %{c}"

Starting a new language translation

1. Create a directory under po named language's ll or ll_CC code. For example, it for Itailan, ja for Japanese, zh_CN for Simplified Chinese.
2. Run rake updatepo. This will create po files for locales if they do not already exist.

Contributing translation to version control

After editing po files, you should use the normalizepo task in the Rakefile before committing to rbot's version control. It avoids unnecessary diff caused by different defaults on committers' gettext tools.