Text and Localization in the EUI
The EUI uses the $ewText.get
method, along with key and value pairs in translation.properties
, to display text on the interface. When the $ewText.get
method contains a particular key, the key's corresponding value is inserted wherever that key appears. This allows the EUI to provide support for multiple languages and facilitate localization. By using these key and value pairs, a full translation of the EUI can be created by simply copying the translation.properties
file and translating the value for each key.
The translation.properties
file only allows you to create a full translation of the system text, such as menus, tabs, buttons, and page titles. You cannot translate the text contained in records with this method.
Displaying text in the EUI with key and value pairs also creates consistency and allows you to easily make changes. If you need to make a terminology change, it's easier when the text values are contained a single file that each page can reference. For example, if you decide to change the name of a table from Support Cases to Support Tickets, you can go to translation.properties
and make that change in one place to propagate the change anywhere the table name appears.
Prerequisites
Before making changes to the EUI, we recommend that you have a basic understanding of the following topics:
- HTML
- CSS
- Macros, methods, and conditionals, as they're used in the EUI
For more information on HTML and CSS, visit W3 Schools.
Working with Text
If you want to change text on the EUI, you need to edit the key to which the text corresponds in translation.properties
. Although it is possible to enter text directly on an EUI page, we recommend using the key-value pairs in translation.properties
for consistency across the EUI templates, as well as to facilitate any future localization efforts.
To change text on the interface:
Open
translation.properties
and search for the text you want to change.Key-value pairs are organized by function and then by table.
- Make the change to the text. Be careful not to remove the equals sign (=) or the text that precedes it.
- Click Save.
- Open the corresponding EUI page and confirm that the text is updated. Remember, if the key to which the text corresponds is used in more than one place, the updated text will appear in the EUI in more than one place too.
Localization with ewText.get and translation.properties
The purpose of the $ewText.get()
method and the translation.properties
file is to allow for a multilingual environment. This is possible because translation.properties
is actually a part of a family of files, with the default setup also including several translation_XX.properties
files, where XX is the is a proper Java 7 locale code. These additional files hold the text for the language indicated by the locale code, and translation.properties
holds the text for English.
When the system sets the locale for each user session, the $ewText.get
method checks the session locale and uses that to determine which translation.properties
file to use. For instance, consider this key and text value pair from translation.properties
:
home.hc.my.link=My Cases
The key is home.hc.my.link
, which is followed by an equals sign (=
), which is then followed by the text value "My Cases." Whenever $ewText.get("home.hc.my.link")
appears in an EUI template, "My Cases" is displayed in the EUI when English is the locale. However, if the locale is not English, the value displayed in the EUI is whatever translation of "My Cases" is in the corresponding translation_XX.properties
file.
If you add other languages to the system, the corresponding language file must be named translation_XX.properties,
where XX is a proper Java 7 locale code. You can find a list of supported Java locale codes here. For more information on the localization process, see Localization.
Set the Session Locale
There are a few common ways to set the session locale:
- Add lang=XX to the login URL.
- Use the #ew_languages macro in
main.php
to display a list of available languages for the user. - Use the #ew_locale macro in
main.php
to set the locale.
If a locale is not set, the default translation.properties
file is used, which is typically English but could in principle be other languages. For more information on
Agiloft's localization-related macros, see EUI Macro Reference.