Localization in RescueMe

RescueMe is localized using the gettext extension. Gettext is a much-used and well-known method of localization, which depends on *.PO files. For compatibility reason, php-gettext is used in font of the raw gettext extension, which have the same API, and the ability to read MO files ("compiled" PO-files) even when gettext is not compiled in or when appropriate locale is not present on the system.

Guides

• [Localization functions](Localization functions)
• [Create a localization domain](Create a localization domain)
• [Localizing strings in a domain](Localizing strings in a domain)
• [Translate localized strings with PoEdit](Translate localized strings with PoEdit)
• [Translation RescueMe into a new language](Translation RescueMe into a new language)

###Recommended editor

It is recommended that developers use the free and easy-to-use PoEdit to edit PO-files. Windows and OSX users can download the binaries from the PoEdit homepage. Linux users could install directly from source, or install any version available from upstream repositories.

###File structure in RescueMe

There are already hundred of single words and longer sentences in the source code. Words and sentences are added and modified continuously, which makes it a big job to maintain many languages. Even a change of case in a word, or comma in a sentence, produce a new text identifier, which in most cases breaks any former translations, forcing the gettext layer to default to en_US for that identifier. With the number of strings we have already, it is important to be able to prioritize between the important and less-important ones.

RescueMe is divided into two logically different parts, an admin interface (operations) and a trace interface (mobile being traced). Both interfaces share some common strings, but for the most part, strings are different. The number of strings in the admin interface greatly outnumbers the trace interface. On the other hand, the number of languages we ultimately need to support in each interface is opposite. We should ideally support all languages in the trace interface to ensure that every user mobile user in the world is able to understand the messages from RescueMe. But we do not need to do the same with the admin interface. If we chose to use only a single PO-file, it would become very cumbersome to maintain 150+ languages when only a small number of strings need translation to each language.

This distinction led to the following localization file structure:

RescueMe locale

src/locale/
├── domain
│   └── common.domain.php
│   └── locales.domain.php
└── nb_NO
    └── LC_MESSAGES
        ├── common.mo
        ├── common.po
        ├── locales.mo
        ├── locales.po

where nb_NO is the Norwegian translation of strings in all interfaces.

Admin interface

src/admin/locale/
├── domain
│   └── admin.domain.json
│   └── admin.domain.php
└── nb_NO
    └── LC_MESSAGES
        ├── admin.mo
        ├── admin.po
└── translate.json.php

where nb_NO is the Norwegian translation of the admin interface.

Trace interface

src/trace/locale/
├── domain
│   └── trace.domain.php
└── nb_NO
    └── LC_MESSAGES
        ├── trace.mo
        └── trace.po

where nb_NO is the Norwegian translation of the trace interface.

SMS messages

src/sms/locale/
├── domain
│   └── sms.domain.php
└── nb_NO
    └── LC_MESSAGES
        ├── sms.mo
        ├── sms.po

where nb_NO is the Norwegian translation of the sms interface.

###Localization domains

Each domain contains all localized strings defined as constants. This simplifies the reuse of common words and sentences throughout the application. There are four domains in total:

Domain
common	Domain shared by all other domains. This domain is loaded for all interfaces.
admin	Domain loaded for the admin interface.
trace	Domain loaded for the trace interface.
sms	Domain loaded when the any interface need to use the SMS subsystem.

Domains are loaded using the function set_system_locale(string $domain, string $locale), which loads the associated domain file(s).

###PO-files

There is one PO-file for each translation of a domain. Each PO-file is associated with a base path and one or several folders relative to this path.

File	Folders
admin.po	admin	Admin interface
trace.po	trace	Trace interface
sms.po	sms	Shared SMS messages
common.po	locale/domain	Common to all domains
locales.po	locale/locales	Localized country names