Localization: Multi-Language Support

When localizing an application for multiple groups of users, each with different language or localization requirements, you must use the multi-language method of localization. This localization method allows for different localization override values to be used for different groups of users without the need for multiple Agentry Server installations.

With multi-language support, multiple sets of localization override files are used, with each set containing the translations for one of the languages. The localization files are then made available to the Server. During transmit, Clients receive the override values from one of the sets of localization files based on the client device’s locale settings.

You must name the localization files based on the settings in the [Configuration] section of the Agentry.ini configuration file for the Server. There are two additional settings within this same section related to the multi-language localization method. All localization settings are listed here, followed by a discussion of how the localization override files are named.
  • localizations
  • localizationsPath
  • applicationStringsFile
  • applicationGlobalsFile
  • clientStringsFile

The localizations setting contains one or more locale name values. A locale name is defined as a text value containing the language name and local of a supported language for the application. The language name indicates the language used (e.g., English, French, Spanish). The locale is the sub-language, dialect, or region for the language (e.g, United Kingdom, Canada, Mexico). The combination of the language name and locale produces the locale name used by the Server to identify the language overrides for a particular Client.

The supported languages must be listed in the localizations setting of the [Configuration] section of the Agentry.ini file. Each language is identified by its locale name. The values for this setting are separated by semi-colons when multiple language names are listed. The specific values are the locale names for the desired languages as listed on the Microsoft Developer Network web site at the following URL: 
http://msdn.microsoft.com/en-us/library/ms776260(VS.85).aspx

This page contains a table with several columns related to language names, locales, and similar information. The column whose value is important here is the one labeled Locale Name. Each locale name consists of the language name followed by the locale, with the two values separated by a hyphen. For example, Spanish is represented by the language name es. There are several different locales for Spanish. Two of these are Spain and Mexico, which are represented by the locale values ES and MX, respectively. The resulting locale names are es-ES for the Spain dialect of Spanish and es-MX for the Mexican dialect. To support these two locales within the application, list the two locale names in the localizations configuration option.

The actual override, or translated values, are contained in the localization override files. When using the multi-language localization method, one set of files is created for each locale name listed in the localizations setting. The names of these files must include the locale name to which they pertain. Specifically, the locale name must come after the other portions of the file name and before the extension. The locale name is separated by periods. Following is an example of the ApplicationText.ini file name for the Mexican-Spanish locale name:
ApplicationText.es-MX.ini

The es-MX portion of the name indicates that the overrides in this file are provided for support of the Spanish language, Mexican dialect locale. This locale name must be the same as the one listed in the localizations setting. The other localization file names are of the same format.

Another impact on the file name is the setting in the [Configuration] section of the Agentry.ini file. If the name of the override files are changed in this setting, that alters which file name the Server looks to read in when started. Using the ApplicationText.ini file as an example, this file is named in the setting ApplicationStringsFile. If the value of this setting is changed to AppTxt.ini, the localization override file name must reflect this value. In this case the file name would be:
AppTxt.es-MX.ini

While it is possible to change the settings of the Agentry.ini file to look for different file names, this is not a recommended practice in most situations. The ability to change these names is provided for the sake of comprehensiveness. Unless dictated by specific implementation or deployment needs, it is recommended that the localization override files are named to match the default settings for these options.

An additional option for supported languages is to provide for a base language that is used without concern over a locale. In this case, the language name of the language is listed in the localizations option. An example of a base language is simply Spanish, which has a language name of es. Specify a base language for one of two reasons:

  1. It is possible that a Client will send a locale name that is not listed in the localizations option.
  2. It may not be necessary to distinguish between one local and another. Simply supporting a language is sufficient.
If a base language is listed in the localizations option, Clients whose language name portion of the provided locale name match that base language will receive the corresponding overrides. As an example, assume the following option is set as shown:
localizations=es-ES;es-MX;es

The supported languages, then, are: Spanish as spoken in Spain; Spanish as spoken in Mexico; and Spanish. If a Client’s locale name is transmitted to the Server as es-ES or es-MX, that Client will receive the corresponding overrides from the localization files for the specified dialect. If, however, a Client’s locale name is es-PA, which is the locale for Spanish - Panama, neither of the first two configured locales match. If no other option is provided, that Client will receive the defined display values as set in the application project.

However, since the language name es is listed in the localizations setting, the Client will receive the override values from the localization files for Spanish. This, results in the Client receiving overrides that, while they are not ideal for the users’ native dialect, are likely to be far better than the defined language of the application, which may not be in Spanish but in English.

The format of the localization file names for such a base language is similar to those discussed previously. The difference being that any locale portion is omitted from the name.
ApplicationText.es.ini

The above example contains the language name es. The overrides in this file are the ones sent to Clients providing locale names for Spanish, but not Spain or Mexico.

It is also possible to use both the single language and multi-language methods for the same implementation. In this case, the override files provided for the single language method, that is, the ApplicationText, ClientText and ApplicationGlobals files that do not include locale names, act as default values.

Assuming that the definitions are created in one language, with overrides provided using both the single language and multi-language methods, the following list provides the order used to determine what value is sent to the Client for display. This order of precedence also applies to values overridden in one localization file but not another, or values not overridden at all.
  1. The Server first attempts to exactly match the locale name received from the Client to the options in the localizations setting. If a match is found, the corresponding localization files are used and all values in these files are sent to the Client. If a match is not found for the Client’s locale name in the localizations configuration option, or if one or more values are not overridden in these files, then...
  2. The Server determines if the base language of the Client’s locale name is listed in the localizations setting. If a match is found for the language name, the corresponding override files are used. Any values found in the base language files are not used if they are already overridden by the more specific locale name override files. If a match is not found for the Client’s base language in the localizations configuration option, or if one or more specific display values are not overridden by these localization files, then...
  3. The single language override files and any override values in the files, if present, are processed. Any overlaps for individual override values between these files and those localization files processed before them are not used. If the single language override files are not present, or if one or more specific display values are not overridden by these localization files, then...
  4. The defined values from the application project are used.
Parent topic: Localizing Agentry Applications