Portable has largely been English (Great Britain) only. While this worked fine when it was a niche project and did not have any “User Interface”, things have changed when we introduced “Dynamic Permissions”:

en_GB

We are introducing GNU gettext for localising Portable. This article will walk through basic principles of GNU gettext and how to translate Portable.

zh_CN

Text Domain

A text domain is several dedicated translation files stored on disk for each language. There are several file types that are worth noting by their extension:

  • .pot: GNU gettext message catalogue template, ASCII text
  • .po: GNU gettext message catalogue, Unicode text, UTF-8 text
  • .mo: GNU message catalog (little endian), revision 0.0, 14 messages

Every program has it’s own Text Domain, for Portable the ID is org.kraftland.portable.

It may seem a bit confusing for 3 different types hanging around here, but it’s actually straightforward when you understand how a translation of supported program forms.

Preparing the program

To translate content, we must first import the gettext code. For Rust programs, it is simply steps away:

  1. Import the relevant crate: cargo add gettext-rs --features 'gettext-rs/gettext-system' (Notice that we enabled the gettext-system feature, because Portable mostly run on glibc systems)
  2. Initialise gettext in a synchronous state (setlocale is not thread-synced):
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
fn main() -> Result<(), StartError> {
match unsafe {
gettextrs::TextDomain::new("org.kraftland.portable")
.codeset("UTF-8")
.init()
.expect("Could not initialise gettext")
}
{
Some(_) => {}
None => {
#[cfg(debug_assertions)]
eprintln!("Could not initialise i18n support");
}
};

main_async()
}
  1. Mark Strings translatable. In essence, replace &str with gettextrs::gettext(&str):
1
gettextrs::gettext("Allow While in Use")

That’s it for the code source.

Extracting translatable content from the program

The next step is preparing a .pot template for other languages to use. For this step we’ll use the built-in xgettext program that comes with gettext as it is Rust-ready:

1
2
3
4
5
6
7
8
9
xgettext \
lib/config/src/definitions/consent.rs \
src/pref/permissions/consent/impls/ask/zenity.rs \
--package-name="org.kraftland.portable" \
--package-version="0.1.0" \
--copyright-holder="Kraftland Organisation" \
--language=Rust \
--from-code=UTF-8 \
--output=po/messages.pot

This saves the translation template into po/messages.pot and it gives you a glimpse of how .po files write in syntax.

For each language, the template can then be adapted to them using msginit:

1
msginit --input=po/messages.pot --locale="${locale}" --output-file po/"${locale}.po"

This .po file can the be opened by a dedicated editor, or any text editor to translate original messages to their native locale.

Essentially, those strings that was marked as translatable before appears in a msgid block, resembling the original en_US locale. When initialising gettext, it will find the appropriate compiled locale.mo file, for example /usr/share/locale/zh_HK/LC_MESSAGES/org.kraftland.portable.mo. If it does not exist yet, fall back to compiled in static Strings (en_US).

Translators’ note

If you are a keen translator, it is very easy to translate Portable to your native language. It requires a basic knowledge of git operations and a Linux computer capable of running gtranslator.

  1. Fork Kraftland/portable into your own repository.
  2. Clone your repository to local using git clone <address>.
  3. Navigate to po/ in the project directory.
  4. Open <locale>.po files using Translation Editor, save and close when you are done.
  5. Commit your changes and push it back up.
  6. Open a Pull Request towards Kraftland/portable:master.

Happy translating!