Overview of Localization in Agentry

Agentry applications provide full support for localization of the mobile application without directly modifying the definitions of the application project. This includes localizing the application for one or more languages with a single Server deployment, as well as localization for the purposes of industry- or deployment-specific terminology.

This support is provided using override files referenced by the Server. An application is localized based on certain options in the Agentry.ini configuration file, and by making use of the localization override files.

Localization base files are files created by the Agentry Editor during a publish. Contained within them are the display values and enable switches that allow the localization of an application. All localization base files include the text Base in the name, as in: ApplicationTextBase.ini. The publish wizard provides a check box allowing you to explicitly create these files.

Localization base files are copied and modified, creating the localization override files. The contents of these files are intended to override the defined values of the application. These files are read and processed by the Server upon startup. The override values are then sent to Clients during synchronization, after application definitions are synchronized but before production data is processed.

The different base files are intended for different aspects of the application and the Agentry software components. The initial contents of the base files are based on the definition of the application. The values contained in the files are those defined to display to the user. This allows the translator or implementor to view the current values and to override them with the localized values for an implementation.

The localization files created for an application are reusable for other implementations of the same application. While customizations are normally a part of the implementation process, localization override files created for the standard deployment of the application provide a good starting point. If managed properly, override files can be created for an application in multiple languages. The files can be created a single time, and used repeatedly for deployments with the same general localization requirements.

Localization Configuration Options

There are several options within the [Configuration] section of the Agentry Server’s properties that can impact the behavior of the localization functionality. These items can be configured using the SAP Control Center. The following options are those that pertain to the localization behavior:

localizations: Use to specify which languages are supported by the application. This controls which override files the Server looks to read in when it is started. This option may or may not be needed, depending on how the application is being localized.
localizationsPath: An optional setting used to specify where the language-specific override files are located. The default is a sub-folder to the Server’s installation folder named localizations and is used when this setting is not listed or has no value set.
Override File Names: There are several additional options in this section you can set to the name of the localization file for a specific area of the Client’s UI. The impact of these settings on the Server’s behavior differs depending on how localization is implemented. These settings are:
- applicationTextFile
- clientStringsFile
- applicationGlobalsFile

The [Configuration] section contains additional options to those listed here, including reference to certain override files (enableOverrideFile, transmitConfigurationFile). Only those options discussed here pertain to localization behavior.

Localization Files

There are two types of files to work with when localizing an application: localization base files and localization override files. Both types of files are formatted in plain text. Open and edit these files in a standard text editor.

Localization base files can be created automatically as an option during publish of the application project from the Editor to the Server. The contents of these files are based on the definition of the application. These, then, are the base files from which override files are created.

Localization override files are those created by a translator using the localization base files as a starting point. The final contents of the override files are the localized or translated display values for the application. Each localization base file results in one or more override files.

Localization Base File List

The following files comprise the localization base files created by the Agentry Editor:

ClientTextBase.ini: This base file contains display values that are a part of every Agentry Client regardless of the application deployed. Values are displayed in the menus and built in screens of the Client. The file contains a single section named [Strings].
GlobalsBase.ini: This base file contains the group, name, and defined values of all globals defined within the application. Each global group has a corresponding section denoted as [GlobalGroupName]within the file. Listed within a section are all the globals in the group and their defined values. Changing the value in this file will override the value of the global sent to the Clients.
ApplicationTextBase.ini: This base file contains one section for each module defined within the application denoted as [ModuleName] and an additional section for the application definition itself, named [Misc]. Every definition within a module containing a display name, label, or caption attribute is listed in this file. The key portion identifies the specific definition and the value contains the display name text. Changing the value in the override file overrides the display name for that specific definition.
TransmitConfigurationsBase.ini: This base file is not a part of localization as it relates to translation. Its usage is described in the information on Client-Server communications within Agentry.
EnablesBase.ini: This base file contains one section for each module defined within the application, denoted as [ModuleName]. Each section lists all actions, pushes, detail screen fields, and list screen columns defined within the module. The value of each item is either true or false. It is likely that most of the values are set to true, unless the definition in question is defined to be disabled in the application. The override file created from this base file can contain items with a value of false to disable the corresponding definition or true to enable it. Disabling a definition will have a different impact depending on the definition type. Disabled fields and columns are not displayed on the Client. Disabled actions are always disabled and users cannot execute them. A disabled push will result in all behaviors related to that push being disabled. If there are no enabled pushes, and background sending is not enabled, users will not remain logged into the Server regardless of the transmit configuration definition.

Working With Localization Override Files

When creating the localization override files it is important to understand that the files are independent of one another. If all planned overridden values exist in one file, it is not necessary to create the other override files. Only those files containing values to be overridden are necessary.

Items within a single file are also independent values. A single override file only needs to contain the items for values to override. If other values within the file continue to use those settings defined in the application project, it is not necessary to list them in the override file.

In both cases, the defined display values and/or behaviors will always default back to the application definitions within the agentry application project. Omitting a particular override will not cause issue with the application behavior on the Client.

Localization Methods

When localizing an application, first determine the best method of localization. This determination is based on the needed language support, specifically whether multiple languages are needed for the same deployment or just a single language for all users.

If all users require the same localization overrides (i.e., a single language) use the single language localization method. If multiple languages are necessary for a deployment, you must use the multi-language localization method. You can also use the multi-language method in deployments where only a single language is needed. Do this to provide for future needs where multiple languages may be provided for the same deployment.

The primary differences between these two methods of localizing an application are:

The Single Language method requires a single set of localization override files; the multi-language method requires one set of override files for each language.
The multi-language method provides for the same base language with multiple locales. As an example, implementing Spanish as the base language, with two locales of Chile and Mexico.
The single language method displays the same override values on all Clients, regardless of the devices’ locale settings; the multi-language method uses the Clients’ locale settings to determine the required override values.
Use of the multi-language method requires knowing the proper language name and locale, collectively referred to as the locale name, for each of the languages supported in the deployment. This method also requires the configuration of client devices with the proper locale settings. The single language method does not make use of locale settings and therefore does not require this information.

Regardless of which method is used, the localization override files are created in the same manner. The localization method used dictates the proper names for the override files, as well as their proper location on the file system. The contents and format of the override files for a given language are the same for either method.