Elephant internationalization project aims to create an easy to maintain translation base.
The API
|
i.text |
Results in text in the appropriate language. |
|
i['text'] |
Results in text in the appropriate language. |
|
i_.get('text') |
Results in text in the appropriate language. |
|
i_.get('text', count) |
Results in text in the appropriate language, using the plural and empty variations depending on count. |
|
i_.format('text', argument[, argument][, ...]) |
Formats text in the appropriate language, using arguments. |
|
i[k[key]] |
Results in the text associated to the given key, in the appropriate language. |
|
i_.byKey('key') |
Results in the text associated to the given key, in the appropriate language. |
Hard-coded variations
Elephant i18n accepts adding variations to a single key. Those variations are singular and empty when the key contains a number formatting symbol like %d and %f, and their own variations.
They are applied when the i_.get('text', count) is called, count will replace the formatting symbol and a variation will be selected depending on count value. For > 1 the basic key, for =1 the singular key and for =0 the empty key.
Handling gender
Handling gender with i18n tools has always been a hard topic and is a matter of which language you take as reference when writing keys. Let's suppose you are the developer, and you are using English as the main language (Elephant i18n default). Now, you write this in your application:
i_.get("%d selected", images.size())
Some languages apply gender to adjectives, which means that selected will be different depending on what is selected. For example, in Catalan images would be seleccionades and files seleccionats. Gender might be different in other languages, and the API makes no hard-coded assumptions.
Elephant i18n approach to solve this problem using key discriminators. Key discriminators generate a different key, but do not show when rendering the translation. A discriminator is a sequence of lowercase letters, up to three, prefixed with the exclamation character. For example !f.
Elephant translations use English as the main key generator and Catalan as the gender reference. An example to solve the previous example would be:
i_.get("%d selected!f", images.size()) i_.get("%d selected!m", files.size())
In this example, English will show the same message (n selected) and will generate two different keys, allowing translators to apply gender to their translations. Elephant convention uses !f for female and !m for male.
Another approach would be using the discriminator to describe the noun, for example !img for images and !fil for files. This solution involves a more developed set of keys and arises the question about why not using the noun in the message (%d selected images).
Notice that the Translator API showing other language translations, tends to facilitate recognizing the pattern. Anyway, a full knowledge of how many languages and languages themselves, would be necessary to fully understand, and maybe solve, the problem. Discriminators are just a none hard-coded help. And there is always the try/error approach.
Translators
Elephant I18n recognizes translators as a specific actor. A translator can be assigned to a single language, to a partial set of languages, or to the whole site set.
Elephant I18n also provides an editable translation for the whole site set of languages, when adding entries.
Migration
The new API features a compatibility wrapper to allow a slower adoption. The compatibility wrapper does not solve all cases, particularly those scarcely in use.
The main difference between both APIs, compatibility and I18n, is the key treatment. I18n use keys only internally. In code you will only see readable text.
Compatibility table
|
Old API |
Compatibility API |
Elephant I18n |
Covered by compatibility |
|
labels.key |
labels.key |
i.text |
|
|
labels['key'] |
labels['key'] |
i['text'] |
|
|
el_label.key |
el_label.key |
i.text |
|
|
el_label['key'] |
el_label['key'] |
i['text'] |
|
|
labelAPI.getStringPars(key, ...) |
i_.c.format(key, ...) |
i_.format(text, ...) |
Requires changing the call, but accepts using key. |
|
el_cons.currentLocale |
i_.used().language |
i_.used().language |
Requires changing the call. |
|
el_cons.usedLocale |
i_.used() |
i_.used() |
Requires changing the call. |
By key
Even though this API aims to create a more readable code, still exists some hardcoded keys that need translation. Example of those are languages codes and Java enums. If everything were to be converted to natural language, the relation with codes will be broken. The ByKey extension allows to keep one to one relation between coded keys and natural language. Also, enforces Elephant I18N by creating the natural language related to the key used by this API.
I18n lanes
