Updated i18n functionality has been pushed to the FarCry 5.1 release. Once the initial 5.0 release is stabilised and the volatility of label changes has come down, we'll activate and test all the great i18n code that has been created to date.
Overview
The webtop and COAPI (meaning all forms that use formtools) have been updated so that every label and description is translated.
A resource bundle is a file that provides translations for in a particular language and region. As well as key-translation pairs, they typically also contain meta-information about a key-translation such as comments, creator, and modifier.
In FarCry resource bundles are stored in /packages/resources/ in core, a plugin, or your project. Their filenames are in the form admin.properties (the default resource bundle) or admin_xx_yy.properties (where "xx" and "YY" is the locale, the language and region codes, of the translation).
When a resource is requested - for example the label on a "Cancel" button - the system first looks in the bundle for the user's locale, then in the default or base bundle.
Translators
Translating is very straight forward. Open the base resource bundle (admin.properties) for the core/plugin/project in a resource bundle editor like RB Manager or the Eclipse ResourceBundle Editor. Use the tool to create a bundle for the locale you require e.g. en_AU (Australian english), and start translating the key-translation pairs.
Regarding keys: At the moment no comments are stored for resources to say where they are used or how. Instead that information is encoded in the resource key. For example webtop labels and descriptions are stored inside a structure corresponding to the webtop structure - webtop.admin@label, content type forms are stored in a structure like coapi.typename.properties.property@label. Other keys reflect the area of the webtop (e.g. fixtree) or part of FarCry framework (e.g. workflow) they are used for, the use (e.g. workflow.buttons), the specific page element (e.g. workflow.buttons.save), then the element attribute (e.g. workflow.buttons.save@label).
To test the translation you need to make sure that the locale you have set up will be loaded in your test project. The project locales are set in the farcryConstructor file in your project www directory. Once this setting is up to date and you have saved your new bundle in the relevant /resources directory, restart the application.
Log into the webtop, edit your profile, select the new locale from the list, and save. When you reload the webtop you should find that is using your translations.
Some webtop elements are available as translated content but aren't included in the base bundle, and others are completely hard coded. An online tracking solution for these elements is in the works, but for the moment these should be documented in a ticket.
Developers
Resource bundles are accessed by FarCry automatically through the webtop and the content type translations, and manually through the application.rb component.
Webtop
Previously the webtop was translated by setting the label attribute in the xml to a variable (refering to the resource bundle struct in memory). With the refactoring, the label attribute is used to specify the DEFAULT VALUE. If the menu item has no corresponding resource, the default will be used. If it does it will be translated. This process also applies to the Inline Webtop Documentation feature.
By default the menu item is mapped to a resource key in the format webtop.sectionid.subsectionid etc. The attribute is then added to this base key to differentiate it from other translated attributes. e.g. webtop.sectionid.subsectionid@label.
The base key used for a menu item can be overridden by setting the rbkey attribute. This means that if you have an equivelent item in two places on your webtop you can override one to refer to the other. NOTE: this is not recommended - context is a significant factor when translating.
COAPI
Translations of type, rule, and form text can currently be accessed through various i18n methods. In most cases these won't be necessary as all formtool tags are now automatically translated.
Manual access - application.rb
application.rb.getResource(key, default, locale)
Argument |
Description |
Default Value |
|---|---|---|
key |
The key being requested |
For consistency should be in the form category.subcategory.item@attribute, e.g. myplugin.thatform.thisdescription@text |
default |
The default value (used if the key isn't found) |
The key string |
application.rb.formatRBString(rbString, substituteValues, default)
Argument |
Description |
Default Value |
|---|---|---|
rbString |
The key being requested. Not changed to key for backwards compatability |
See getResource |
substituteValues |
Either a simple value to replace one value or an array to replace several. Variables defined in the resource string as {1} ... {n} |
Required |
default |
The default value (used if the key isn't found) |
The key string |
Creating the base bundle
Developers who want to support community efforts to translate their plugins should include a complete base resource bundle in their project. To recap: this is a file called /packages/resources/admin.properties in your plugin. This isn't necessary if the code is not going to be released or if you're happy for other developers to complete this next step. By default FarCry handles the lack of a resource bundle invisibly by returning the default values provided in code.
The Resource Bundle Plugin provides functionality for automatically generating bundles based on default values, base bundles, or even with the Google Translate API. But it is important to remember that the automatic generation of the base bundle only handles resources that have been "touched". This means that a button label (for example) will only be known to the plugin if you have actually accessed the form.