This section contains the following topics:
SmCPW, APSAdmin & Forgot (User Interfaces)
Note: As every developer that has ever attempted it knows, internationalization is a very complex subject. This section is not intended to be a treatise on internationalization; it is intended only as instructions and guidelines for using the internationalization features of APS to localize its functionality at your site.
Internationalization is the capability of a program to be localized, that is, to vary the display of information based on where the user is and what the user (and the user's browser) is capable of. Typically, this is primarily equated to language translation, but may include more than that.
For example, most Canadians speak English, but Canada is not divided into "states"; instead, it is divided into "provinces". To vary the output for Canadian users to display a prompt as "Province" instead of "State" is part of localization. Whereas internationalization is the capability, localization is the actual implementation for a specific locality; a locality being defined (at least for our purposes) as a combination of language and country code.
Every piece of text or graphic presented to a user by APS can be modified by a site. For our purposes, the word translation can be used, though it is not entirely accurate in the traditional sense, just as localization is not strictly language translation.
Every error message, prompt, and result is stored within the APS programs as a key. With each key is a default translation. During processing, APS asks the APSXlate library for text associated with the key. If there is no text associated with a given key, APS will use the default text. All default text is in US English.
APSXlate uses translation files to look up text for each key. When APS asks for a translation, it tells APSXlate what the user's language and country settings are. APSXlate then will select the appropriate files to use to look up the correct translation.
These translation files are stored on both the Policy Server and on the Web Server. Under Windows, they are stored in a directory called Language that must exist as a subdirectory under where APSXlate.DLL is located. Under Unix, APSXlate uses an environment variable to locate the Language directory.
Under the language directory, there are subdirectories for each language and locality. For example, there should be directories called EN and EN-US. Files located in the EN subdirectory are for general English and files in EN-US contain overrides that are specific for English in the United States. APSXlate loads files from the EN directory first, then loads files from the EN-US directory, the EN-US translations overlaying any duplicate entries loaded from the EN directory.
There is actually a total of up to four files loaded by APSXlate for any translation; "Common" files and files that are specific to an application. The details of how files are loaded and reloaded are detailed in the APSXlate documentation. What you need to know here is the names of the files that APS uses.
SmCPW (the web-server-side CGI program users access to change their passwords) uses a file called SmCPW.lang, stored in the language directories on the Web Server. APS uses a file called APS.lang, stored in the language directories on the Policy Server. There may be multiple copies of each of these files, one for each locale supported by the site.
Within each file, there are definitions for each key and the translation for that key. To change the text associated with a given key, locate the key within the file (for the target language) and change the associated text.
The keys should never be changed, since the key is what is used to locate the text. Only the text should ever be changed.
Since every text string is "translated", even from English to English, you can change the actual text for every message in the system by modifying the translation files.
The files, as supplied, contain all default strings. If you were to delete the translation files (this is not recommended!), the default text would still be displayed to the user, because it is actually hard-coded into APS. The advantage is that if the user's locale has no translation files (for example, he wants Greek), the default English translation will still be used.
There are three points of contact between APS and the user:
SmCPW (change password interface), APSAdmin (help desk interface) and Forgot (part of the FPS interface) can infer the user's locality from information passed from the user's browser. The rules for determining the browsers language are:
If so, its value is the name of a cookie to use. The cookie should contain the desired language information using the same format as the HTTP accept-language header. It will be processed instead of the value of the accept-language header. No other responses or cookies are examined.
If so, their values indicate the actual ISO language and country codes to use. No additional processing will occur.
The resulting string (either from the cookie or the HTTP header) is evaluated from left to right to find a supported language/country combination. If any combination has full support (both language and country), it will be used, otherwise, the first value with a language only match will be used.
If no match can be found, US-EN will be used.
The default form that SmCPW builds uses translations for all prompts, window titles and messages. These all come from the SmCPW.lang file. To support multiple locales, copy the default SmCPW.lang file to each required locale (directory) and translate the messages for the appropriate language.
To modify a default in English, just modify the English language file.
Of course, your site can always use a custom form and handle the form localization yourself.
Error and confirmation messages used by SmCPW originate from either the SmCPW.lang file or the APS.lang file, depending on where the message actually originated. Just locate the desired message to translate and change it, either in the English language file or in the language appropriate for the change.
For all such error messages, regardless of where it originates, if it "looks" like a URL, SmCPW will redirect the user rather than displaying the message. Thus, you can do your own localization by redirecting messages to known Web Pages that do their own translation.
If you want to entirely do your own translation, you should set the SM_LANGUAGE and SM_COUNTRY responses for SmCPW to EN and US. Supply your own form (that adapts to the user's locality) and modify all of the EN-US message translations to URLs instead of text. In this case, SmCPW will display no messages itself, it will just redirect the user to pages that can adapt themselves. The full capabilities of SmCPW are detailed elsewhere in this document.
The forms that APSAdmin builds use translations for all standard elements, window titles and messages. These all come from the APSAdmin.lang file. To support multiple locales, copy the default APSAdmin.lang file to each required locale (directory) and translate the messages for the appropriate language.
Section labels and field prompts are specified in the [APSAdmin] section of APS.cfg and are not normally translated. If translation for these elements is desired, put a pound sign ("#") in front of the prompt definition in APS.cfg. This tells APSAdmin that the prompt should be translated. The key for translation is the full prompt value (including the "#") and the default translation has the "#" removed.
To modify a default in English, just modify the English language file.
APS does not actually display its own messages when an authentication-time event occurs. Instead, it redirects the user to particular pages. There are two ways to localize this communication.
One way is to create a "generic" page for each type of redirection that performs its own adaptation for the user's locality, much the same as SmCPW.
The other way is to write specific pages for every event for every locality, then perform redirection overrides based on some value in the user's record (described elsewhere in this document). This mechanism is not recommended because of the following case: Suppose the user typically accesses your site from her office in Russia. The preferred language in her Directory entry indicates Russian (which uses a Cyrillic font). Now suppose she's visiting New York and accesses some sort of kiosk browser that does not have a Cyrillic font installed. Since the selection is based on the directory entry instead of the browser entry, the page will try to display Cyrillic text on a browser that does not support it.
Email should always be sent using the language stored in the user's directory entry, if it is available, since 1) the email may not be going to the same user that is trying to authenticate (it could be a hacker) and 2) some mail originate offline, when a browser is not involved.
The easiest way to localize email is to store a copy of each email file for each language in a separate directory, much like the language files. Then, when you specify the Mail Directory in the APS Configuration File, include, as part of the path, the text {preferredLanguage}. APS will replace that text with the user's stored language, thus changing the actual directory that APS will look for the file on. The correct file will then be loaded.
Keep in mind that the Administrator's language will sometimes be different from the user's, so keep in mind who the intended recipient of each email is to be.
See Using Email for more information about handling email.
|
Copyright © 2013 CA.
All rights reserved.
|
|