Text Translation

Text Translation

OFBiz externalizes text presented to the user by keeping it in UI label files. Three file formats are supported:

1. *.properties file that contains the text in key=value format, one file per locale
2. *.xml file using the Java property XML file format, one file per locale
3. *xml file using the OFBiz property XML file format, one file for all locales

All new OFBiz development uses the OFBiz XML file format. This format is preferred because it is easy to edit using Unicode languages, and it also makes it easier to notice missing translations.

Translating Text In The Screen Widgets And Freemarker Templates

Before the translated text can be used in a web page, the appropriate UI label file must be loaded into memory using the screen widget actions element:

<actions>
    <property-map resource="CommonUiLabels" map-name="uiLabelMap" global="true"/>
</actions>

where resource is the name of the UI label file (extension optional) and map-name is the name of the Map that will contain the contents of the UI label file. The keys in the file become the Map keys.

Here is an example of translated text in CommonUiLabels.xml:

<property key="CommonAddNew">
    <value xml:lang="ar">إضافة الجديد</value>
    <value xml:lang="de">Neu hinzufügen</value>
    <value xml:lang="en">Add New</value>
    <value xml:lang="es">Crear nuevo</value>
    <value xml:lang="fr">Ajouter un nouveau</value>
    <value xml:lang="it">Aggiungi nuovo</value>
    <value xml:lang="nl">Voeg een nieuwe toe</value>
    <value xml:lang="pt">Adicionar Novo</value>
    <value xml:lang="ro">Adauga Nou</value>
    <value xml:lang="ru">Добавить новый</value>
    <value xml:lang="th">เพิ่มใหม่</value>
    <value xml:lang="zh">新建</value>
    <value xml:lang="zh_CN">添加新的</value>
</property>

If we want to display this text, we simply reference it using String expansion:

<!-- Screen widget -->
<container style="h1"><label text="${uiLabelMap.CommonAddNew}"/></container>

<!-- Freemarker template -->
<h1>${uiLabelMap.CommonAddNew}</h1>

The text will be translated into the user's language.

Translating Text In Mini-Language

The process is similar in Mini-Language, but the syntax is slightly different:

<property-to-field resource="CommonUiLabels" property="CommonAddNew" field="addNew"/>
<log level="info" message="${addNew}"/>

where resource is the name of the UI label file (extension optional) and field is the name of the variable that will contain the translated text.

Translating Text In Java

Translating text in Java is accomplished by using the org.ofbiz.base.util.UtilProperties class. Here is an example:

public static Map<String, Object> myJavaService(DispatchContext ctx, Map<String, ?> context) {
    Locale locale = (Locale) context.get("locale");
    try {
        // Do something risky
        ...
    } catch (Exception e) {
        return ServiceUtil.returnError(UtilProperties.getMessage(MyUiLabels, "RiskyErrorMessage", locale));
    }
    ...
}