This section contains the following topics:
Several SiteMinder subsystems use the APSXLate library to perform internationalization and localization. The APSXLate library uses translation files to perform its function.
Advanced Password Services is capable of displaying user panels or error messages in multiple languages. It programmatically determine the user’s locality (a combination of language and country) and then use the APSXLate library to translate text for that locality.
The library consists of a single library called APSXLate (a DLL on Windows NT, SO on Solaris) and a single executable called APSXlateTest (an EXE on Windows NT).
A directory called Language is also required. This directory will contain the language translation files.
The APSXLate library locates the Language directory using the following rules.
The library may need to write log information. If so, it will create a log filenamed using the current date in the format YYYYMMDD.log.
These log files will be placed in a subdirectory under the language directory (see above) called "logs", if the subdirectory already exists. If it does not already exist, the files will be placed in the language directory itself.
You can also specify the directory into which the logs are to be placed using an environment variable called APS_LANG_LOGS.
Note that wherever the files are to be placed, the current user must be able to create and write to this directory. If the directory does not exist or is not writable, no logs will be written.
As little information as possible is actually written to the log file, in order to boost performance and reduce the disk space requirements.
Translation file parsing errors, missing translation keys, and reload notifications (this occurs when a translation table is reloaded because the underlying files have changed) are the only items logged at the time of this writing. The DEBUG keyword (usable in translation files, see the next section) may, in the future, cause additional logging to occur.
Log files are only opened when required. Once opened, it will stay open until the process terminates or a log is written on a different date. Therefore, an older file might remain open after its date. The next log will cause the old file to be closed a new one opened.
The log files are primarily used to track missing translations. If an application requests the translation of a key that is not defined in the translation files, the key and default values are logged (the default is recorded so that no logging will occur until the translation files are reloaded).
By periodically watching for log files, a site can tell if unusual languages or countries are being requested or if a translation key is missing from a translation file.
This file is an executable that can be used for testing. Use a command line argument of -? to request its possible command line arguments.
When an application requests a language object from APSXLate, it specifies an application, a language and an optional country. Using this information, APSXLate uses up to four files to build a translation table to use for the locale. Given a language code of EN, a country code of US, and an application of APP, the four files would be (all paths relative to the translation files directory):
EN/(Common).lang EN/APP.lang EN-US/(Common).lang EN-US/APP.lang
Each file’s translation information is loaded, in turn, into the in-memory translation table. If a value already exists when a file is loaded, the existing entry is overwritten by the more specific translation file.
For example, the EN/APP.lang file might define a translation key for "Jurisdiction" that translates to "State or Province". In the EN-US/APP.lang file, the same translation key might translate to "State". In the EN-CA (Canadian English), the translation might be "Province".
Header information (also specified in the translation files) also override previously loaded settings, with the exception of directories (see the description of the DIRECTORY keyword for details).
If a translation value is not found for a given key, the application can specify a default value (usually in US English) that will be returned by the library and recorded in the log file and the in-memory translation table (the translation files are never updated automatically). If no default is specified, the key itself is returned as the value. By doing this, a language which has no translation files will still show up in English. Also, if a key is missing from a translation file, the value will still show in English.
A special exception is the Image Directory and Directory settings. If no value is read from any of the translation files, EN will always be returned, so that graphics can be properly displayed (and external data loaded), even for unsupported languages (albeit only English will be provided).
If a language is requested, but none of the four files can be found, APSXLate will log a message to the log file and will use the settings for EN.
A translate file consists of a file header, which must exist and may not contain embedded blank lines (blank lines may exist before the first header line and at least one blank line must appear after the last header line).
Leading and trailing blanks and tabs are ignored.
Any file beginning with two forward slashes ("//"), a semicolon (";") or a pound sign ("#") are considered comments (trailing comments are not
supported). Comment lines may appear anywhere in the file and are ignored.
Sometimes translation values exceed a single physical input line. Start a line with an ampersand ("&") to continue from the previous line. The ampersand and any trailing spaces are removed and the continuation line is added to the previous line (with a space between).
Continuation lines are not supported within the header section of the file.
The header consists of a collection of keywords, followed by values. The keyword may be separated from its value by at least one space. Additional spaces or tabs are not significant. Keywords are not case-sensitive.
Comments may appear within the header, but once a single header keyword has appeared, no blank lines may appear until the end of the file header. The file header ends when a blank line appears. Note that at least one header keyword is required.
Many keywords have multiple possible spellings or formats.
Long Name <language long name> LongName <language long name> Name <language long name> Description <language long name>
This allows a name to be associated with the language for documentation purposes.
Images <image directory> Image Directory <image directory> Image Path <image directory>
The value for <image directory> is returned to the application when requested. Usually, this is a subdirectory of a general image directory that contains language-specific images. If requested by an application, but not specified in the translation file(s), APSXLate will always return EN, so that English graphics can always be available.
Directory <type> <directory>
The specified <directory> will be returned when the <type> is requested. Directory types used by an application are defined by the application. For DDA, for example, this allows the site to specify directories where email files, list files, and include files will be stored for each language.
Charset <charset value> Character Set <charset value>
The character set code associated with the language. "ISO-8859-1" is used if this value is not specified.
Prompt Suffix <suffix>
Allows the language to specify the suffix to use when an application requests a prompt translation. By default, a colon (":") will be used.
Direction LTR Direction RTL
Specifies the direction used by the language. Currently, RTL is properly parsed, but only LTR is actually used (RTL is ignored). This keyword is for future expansion.
Debug
Turns on debugging for all objects using this translation file. At this time, no debugging code exists, but it may be added in the future.
Buttons are defined using two keywords, each appearing on a separate line.= Each keyword must be followed by at least one space. Additional spaces or tabs are ignored. The keywords are not case sensitive.
Button settings are explicitly requested by applications.
Button <key>
Specifies the key that identifies the button. Applications request values by key, so that all translations for a specific button must use the same key, which is defined by the application. Values for <key> are case-sensitive.
Label <key-label>
Specifies the label to use for the button key defined just previously (using the Button keyword). If not specified for a button, the <key> will be used (useful only for English).
Translations are defined using two keywords, each appearing on a separate line. Each keyword must be followed by at least one space. Additional spaces or tabs are ignored. The keywords are not case sensitive.
Key translations are explicitly requested by applications, either as a "normal" translation or as a "prompt" (in which case the prompt suffix is affixed to the translated value).
Key <key>
Specifies the key that identifies the translation. Applications request values by key, so that all specific translations must use the same key, which is defined within the application. Values for <key> are case-sensitive.
Many keys are actually their English value. This easily ensures that if a key is not defined, at least an English value will be displayed (since the library returns the key if there is no translation defined or a default value supplied by the application).
Value <translation>
If the translation is long, the value for <key> may be encoded (usually with a t_ prefix to prevent naming conflicts). This improves performance when looking up values in the translation table.
Val <translation>
Specifies the translated value for the key defined just previously (using the Key keyword). Translation values may be continued onto the next line as described previously.
|
Copyright © 2013 CA.
All rights reserved.
|
|