test

Technical Note: Sun Java System Access Manager Localization Guide

Technical Note: Sun Java System Access Manager Localization Guide

This document describes the organization of localized Sun JavaTM System Access Manager (Access Manager) software resource files. It also explains how to add a new language to the list of languages supported by Access Manager and how to customize an existing language's resource files.

This document covers the following topics:

Introduction

Access Manager is currently localized in seven languages: French, German, Japanese, Korean, Spanish, Traditional Chinese, and Simplified Chinese. Localizing the administration browser interface in a yet to be supported language can become an issue, as can customizing an already supported language. Access Manager administrators need to know which files store localized messages, where the files are located, and how to add a new language to Access Manager.

This document explains how to organize Access Manager software resource files, add support for a new language, and customize existing software resources. Information about file organization is accurate up to and including Sun Java System Access Manager 7.1. Full usability of this document relies on the accessibility of the Sun Virtual Lab. This document contains sufficient information to customize localization in case the Sun Virtual Lab is unreachable.

Customizing the Localization of Access Manager: One Pager Overview

This section shows how Access Manager files are organized. It also shows the basic steps involved in adding new language support and customizing the Access Manager localization resource files.

Organization of Access Manager Resource Files

Adding New Language Support

Customizing Existing Messages

Organization of Software Resource Files

This section describes how files that contain Access Manager software messages are organized. Access Manager software messages are stored in three file formats:

Software messages displayed in the Administration Console (using a browser) are stored in these two formats:

Software messages displayed in the command-line interface (using a terminal window) are stored in the MO files format.

The next three subsections describe the organization of these three software message formats.

Java Properties Files

Java properties files are resource files that contain most of the software messages to be displayed in the Access Manager Administration Console. Java properties files should be saved in escaped Unicode format. Otherwise, multibyte characters are likely to be incorrectly displayed. To ensure the correct format of Java properties files, after each change, run the native2ascii binary as follows: native2ascii filename

For more information about the native2ascii binary, go to http://java.sun.com/j2se/1.4.2/docs/tooldocs/solaris/native2ascii.html.

Java properties files are located under AM_INS/locale.

Each of the seven supported languages contains 70 Java properties files. The Access Manager Java properties files naming convention is as follows: amfunctionality_locale.properties

Note –

This document uses a Dutch (nl) version of Access Manager as an example language.

Java properties files for the Dutch version of Access Manager are under AM_INS/locale.

The following Java properties are for Dutch language:

XML Files

Access Manager XML files contain software messages to be displayed in the Administration Console. These XML files are used by the authentication service to display the localized authentication (login) screen based on a particular module type. Save XML files under UTF-8 encoding after each modification. To ensure that an XML file is saved under UTF-8 encoding, the Solaris binary iconv can be used as follows: iconv -f current-file-encoding -t UTF-8 filename

For more information about the iconv binary, go to http://docsun.cso.uiuc.edu/sun_docs/C/solaris_9/SUNWaman/hman1/iconv.1.html.

Access Manager XML files are located under this directory: AM_INS/web-src/services/config/auth/default_locale/

For example, the location of the XML files for the Dutch version of Access Manager is the AM_INS/web-src/services/config/auth/default_nl/ directory.

The following XML files are for the Dutch version of Access Manager:

MO Files

MO files are resource files that contain software messages to be displayed in the Access Manager CLI. MO files are commonly generated from PO files. MO files are located under AM_INS/locale/locale.UTF-8/LC_MESSAGES/

Generate MO files in UTF-8 encoding by doing the following:

The msgfmt utility is delivered as part of the gettext package. For more information about this package, go to http://www.gnu.org/software/gettext/.

For example, the location of the MO files for the Dutch version of Access Manager is the AM_INS/locale/nl.UTF-8/LC_MESSAGES/ directory.

The MO files for the Dutch version of Access Manager are as follows:

For instructions on how to generate an MO file under UTF-8 encoding, see Hands-on Lab Format.

Adding New Language Support

Access Manager is an internationalized application that facilitates support for new languages apart from the seven default languages. Administrators can add new language support to Access Manager without having to change the source code.

The process can be divided into two parts:

Adding a New Language to the Supported Language List

Adding a new language to the Access Manager supported language list means that the iPlanetG11NSettings service must be modified as shown in the following examples.

Create two new files and store them in a temporary location.

Example 1 setServiceRevision.xmlFile

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE Requests PUBLIC "-//iPlanet//Sun Java System Access Manager 7.1 Admin CLI DTD//EN" "jar://com/iplanet/am/admin/cli/amAdmin.dtd">

<!-- apply this file by: amadmin -u admin-user -w admin-pwd -t filename.xml -->

<Requests>

<SchemaRootNodeRequests serviceName="iPlanetG11NSettings">

<SetServiceRevisionNumber number="new-revision-number" />

</SchemaRootNodeRequests>

</Requests>

Note –

filename— Name of the file in which XML content will be stored, setServiceRevision.xml in this example.

new-revision-number — Add 10 to the existing revision number. The default value is 0.

To update the iPlanetG11NSettings service, run the amadmin utility as mentioned in Example 1.

Example 2 amG11nSettings_mod.xml File

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE Requests PUBLIC "-//iPlanet//Sun Java System Access Manager 7.1 Admin CLI DTD//EN" "jar://com/iplanet/am/admin/cli/amAdmin.dtd">

<!-- apply this file by: amadmin -u admin-user -w admin-pwd -t filename.xml -->

<Requests>

<SchemaRequests serviceName="iPlanetG11NSettings" SchemaType="Global">

<AddDefaultValues>

<AttributeValuePair>

<Attribute name="sun-identity-g11n-settings-locale-charset-mapping"/>

<Value>locale|charset=charset-list</Value>

</AttributeValuePair>

</AddDefaultValues>

</SchemaRequests>

</Requests>

Note –

filename — Name of the file in which XML content will be stored, amG11nSettings_mod.xml in this example.

locale — Standard ISO language value supported by the browser, for example, nl, ja, or fr.

charset-list — Semicolon-separated list of supported character sets for the language specified by locale, for example, UTF-8;Shift_JIS;EUC-JP.

To update the iPlanetG11NSettings service, run the amadmin utility as mentioned in Example 2.

After the iPlanetG11NSettings service is updated, Access Manager supports the new specified language. To finalize support of the added language, you must add software message resources to this language.

For instructions on how to add a new language to the Access Manager supported language list, see Hands-on Lab Format.

Adding Localization Resources for a Newly Supported Language

This section describes how to add and customize files that contain Access Manager Console authentication interface messages. It then explains how to add and customize the Access Manager Console user interface messages. Access Manager detects the client language that uses information in the HTTP request from the browser. Hence, to add L10n resources for a new language, the only requirement is to follow the Access Manager file name conventions and directory organization.

Localizing Authentication Interface Files

When providing authentication interfaces for localized environments, a separate directory for each language that contains customized XML files must be created. For each language, a subdirectory structure similar to the Access Manager information tree must also be created. The subdirectory starts from the authentication interface base directory, that is, AM_INS/web-src/services/config/auth/default_locale/

The first directory structure is needed to receive the new authentication interface file. This directory structure is then populated with existing interface files. Finally, these files are customized.

For instructions on how to localize authentication interface files for a new language, see Hands-on Lab Format.

The following procedures explain what must be done to localize authentication interface files.

ProcedureTo Create a Subdirectory Structure for the AMRoot Realm and All Its Sub-realms

  1. Open a terminal window (if necessary) on a system where Access Manager is installed.

  2. Navigate to the authentication interface base directory.

  3. Create a subdirectory structure.

  4. Change to the created subdirectory.

ProcedureTo Populate the Created Subdirectory With Desired Interface Files

  1. Copy the default Login.jsp file to the current directory.

  2. Copy the default Logout.jsp file to the current directory.

  3. Copy the default LDAP.xml file to the current directory.

ProcedureTo Customize Previously Copied Files

  1. Open the files in a text editor.

  2. Insert the new strings.

  3. Save the files.

Localizing the Access Manager Administration Console

To add language support to the Access Manager Administration Console, a new Java properties file for the desired module must be created. For example:

Example 3 Adding Language Support for the Policy Module for the Dutch Language

  1. Change to the AM_INS/locale directory.

  2. Copy the amPolicy.properties file to a new amPolicy_nl.properties file.

  3. Modify the created amPolicy_nl.properties file.

  4. Save the file.

  5. Restart the web container.

Another example is the customization of the copyright notice displayed at the bottom of the Access Manager Administration Console Login page.

Example 4 Customizing the Copyright Notice

  1. Change to the AM_INS/locale directory.

  2. Copy the amAuthUI.properties file to a new amAuthUI_nl.properties file.

  3. Modify the copyright.notice key in the created amAuthUI_nl.properties file.

  4. Save the file.

  5. Restart the web container.

After adding support for a new locale to Access Manager, newly added language software resources must be customized as described in the following section.

Customizing the Localization

This section explains how to customize Access Manager software resource messages.

To provide a fine granularity of information, this section introduces a new concept for helping administrators to customize Access Manager localization. This concept binds together usage of the following:

Sun Virtual Lab

The Sun Microsystems Globalization organization has deployed Sun Java Enterprise System Release 5 in the Sun Virtual Lab. External users can freely access an up and running instance of Sun Java Enterprise System Release 5 applications through a browser. To log in to Sun Java System Access Manager 7.1 deployed in the Sun Virtual Lab, enter the following URL into your favorite browser:

To log to the bookshop organization, type the user name and password as follows:

Working With the Sun Virtual Lab

Instances that have been deployed in the Sun Virtual Lab have been modified for the Dutch language. Those instances for this language contain customized software resource files. Java properties files and XML files have been modified in a particular way to help administrators willing to customize the Access Manager GUI. The following subsections explain the modifications made to the software resource files. To see these changes, your browser language setting must be set to the Dutch (nl) language.

Java Properties Files in the Sun Virtual Lab

Major changes in resources were made to the Java properties. Indeed, these files are responsible for displaying almost all messages from the Access Manager Administration Console.

Java properties files are usually based on a key=value system. The key is used as a unique reference to display the value in the user interface. The key is identical in all properties files, regardless of the language setting. The value (which is actually a message displayed in the GUI) is different depending on the language setting.

In the Sun Virtual Lab, almost all occurrences of the value have been replaced by key itself. Java properties for the Dutch (nl) language are now based on a key=key system. Hence, when accessing an instance of Access Manager deployed in the Sun Virtual Lab, the GUI will display key titles instead of key values. A number has also been inserted before each key. For example, the Login button key in the amConsole_nl.properties resources file stored in the Sun Virtual Lab is buttonnew=[33]button.new.

Using the following mapping table, it is possible to locate the resource file in which a key is located. Using the Login button example, it is easy to locate the resource properties key in the system and to customize it.

Table 1 Properties Files Mapping Table for the Dutch (nl) Language

File ID 

File Name 

File ID 

File Name 

[2] 

amAdminConsole_nl.properties

[36] 

amEncryption_nl.properties

[3] 

amAdminModuleMsgs_nl.properties

[37] 

amEntrySpecific_nl.properties

[4] 

amAgent_nl.properties

[38] 

amFederation_nl.properties

[5] 

amAuthAD_nl.properties

[39] 

amG11NSettings_nl.properties

[6] 

amAuthAnonymous_nl.properties

[40] 

amIdRepo_nl.properties

[7] 

amAuthApplication_nl.properties

[41] 

amIdRepoService_nl.properties

[8] 

amAuthCert_nl.properties

[42] 

amInteraction_nl.properties

[9] 

amAuthConfig_nl.properties

[43] 

amLDAPv3Repo_nl.properties

[10] 

amAuthContext_nl.properties

[44] 

amLibertyDSTService_nl.properties

[11] 

amAuthContextLocal _nl.properties

[45] 

amLibertyPersonalProfile_nl.properties

[12] 

amAuthenticationDomainConfig_nl.properties

[46] 

amLibertySecurity_nl.properties

[13] 

amAuth_nl.properties

[47] 

amLogging_nl.properties

[14] 

amAuthHTTPBasic_nl.properties

[48] 

amMeta_nl.properties

[15] 

amAuthJDBC_nl.properties

[49] 

amNaming_nl.properties

[16] 

amAuthLDAP_nl.properties

[50] 

amPasswordReset_nl.properties

[17] 

amAuthMembership_nl.properties

[51] 

amPasswordResetModuleMsgs_nl.properties

[18] 

amAuthMSISDN_nl.properties

[52] 

amPlatform_nl.properties

[19] 

amAuthnSvc_nl.properties

[53] 

amPll_nl.properties

[20] 

amAuthNT_nl.properties

[54] 

amPolicyConfig_nl.properties

[21] 

amAuthRadius_nl.properties

[55] 

amPolicy_nl.properties

[22] 

amAuthSafeWord_nl.properties

[57] 

amProviderConfig_nl.properties

[23] 

amAuthSAML_nl.properties

[58] 

amSAML_nl.properties

[24] 

amAuthSecureID_nl.properties

[59] 

amSDK_nl.properties

[25] 

amAuthUI_nl.properties

[60] 

amSecurity_nl.properties

[26] 

amAuthUnix_nl.properties

[61] 

amSession_nl.properties

[27] 

amAuthWindowsDesktopSSO_nl.properties

[62] 

amSOABinding_nl.properties

[28] 

amBinarySecurityToken_nl.properties

[63] 

amSSOProvider_nl.properties

[29] 

amClientData_nl.properties

[64] 

amUser_nl.properties

[30] 

amClientDetection_nl.properties

[65] 

amUtilsMsgs_nl.properties

[31] 

amCommonUtils_nl.properties

[66] 

amValidation_nl.properties

[32] 

amConfigurator_nl.properties

[67] 

amWebAgent_nl.properties

[33] 

amConsole_nl.properties

[68] 

amWSSecurity_nl.properties

[34] 

amDelegation_nl.properties

[69] 

amWSSProvider_nl.properties

[35] 

amDisco_nl.properties

   

Note –

The original English message can be retrieved by accessing an Access Manager instance with the language browser setting set to English.

The original English value for each key is available in all Java properties files as a comment above each key line.

To find out how to locate Java properties files, see Java Properties Files.

The amAdminCLI.properties file has not been customized.

The amConsole.properties file contains a number of keys that must not be customized:

The amConsole.properties file contains values for time zones. Because those values must not be changed, the list of time zones has been kept as the default.

XML Files in the Sun Virtual Lab

In XML files, messages have been replaced by the name of the file that contains the message, followed by the line number where this message is located in the file. See the following example for more information.

Example 5 Customized DataStore.xml File Stored in the Sun Virtual Lab

<ModuleProperties moduleName="DataStore" version="1.0" >

<Callbacks length="2" order="1" timeout="120" header="AM_INS/web-src/services/config/auth/example_nl/bookshop/DataStore.xml:14" >

<NameCallback>

<Prompt>AM_INS/web-src/services/config/auth/example_nl/bookshop/DataStore.xml:15 </Prompt>

</NameCallback>

<PasswordCallback echoPassword="false" >

<Prompt>AM_INS/web-src/services/config/auth/example_nl/bookshop/DataStore.xml:17 </Prompt>

</PasswordCallback>

</Callbacks>

</ModuleProperties>

Practical Example: Access Manager Administration Console Login Page in the Sun Virtual Lab

When accessing the Access Manager Administration Console installed in the Sun Virtual Lab through a browser with its language setting set to English (en), administrators can see the default Access Manager login page. When the browser's language setting is set to Dutch (nl), the customized login page of the Access Manager Administration Console is displayed.

Note –

To fully understand the following example information, go to http://sears.sunvirtuallab.com:32110/amserver/UI/Login.

The following components are localized:

Hands-on Lab Format

The procedures in the following sections provide a practical summary of all procedures discussed in this document:

These procedures add the Dutch language to Access Manager. Nevertheless, any other language supported by a browser can be added to Access Manager. An example at the end of this section shows how to generate an MO file within UTF-8 encoding.

Adding a New Language to the Supported Language List

ProcedureTo Create the setServiceRevision.xml File

  1. Open a terminal window on the server where an instance of Access Manager is installed (if necessary).

  2. As superuser create a temporary directory to store the XML files used to add support for a new language.

    # mkdir -p /export/am_xml_tmp

  3. Change to the temporary created directory.

    # cd /export/am_xml_tmp/

  4. Create the setServiceRevision.xml file.

  5. Open the empty created file with a text editor and insert the following lines:

    <?xml version="1.0" encoding="UTF-8"?>

    <!DOCTYPE Requests PUBLIC "-//iPlanet//Sun Java System Access Manager 7.1 Admin CLI DTD//EN" "jar://com/iplanet/am/admin/cli/amAdmin.dtd">

    <!-- apply this file by: amadmin -u admin-user -w admin-pwd -t filename.xml -->

    <Requests>

    <SchemaRootNodeRequests serviceName="iPlanetG11NSettings">

    <SetServiceRevisionNumber number="10" />

    </SchemaRootNodeRequests>

    </Requests>

  6. Save the changes.

ProcedureTo Apply Changes to the Access Manager Administration Console With the amadmin Tool

  1. Change to the Access Manager bin directory.

    # cd AM_BIN/

  2. Run the amadmin tool as follows:

    # ./amadmin -u admin-user -w admin-pwd -t \ /export/am_xml/tmp/setServiceRevision.xml

ProcedureTo Create the amG11nSettings_mod.xml File

  1. Open a terminal window on the server where an instance of Access Manager is installed (if necessary).

  2. Change to the temporary created directory.

    # cd /export/am_xml_tmp/

  3. Create the amG11nSettings_mod.xml file.

  4. Open the empty created file with a text editor and insert the following lines:

    <?xml version="1.0" encoding="UTF-8"?>

    <!DOCTYPE Requests PUBLIC "-//iPlanet//Sun Java System Access Manager 7.1 Admin CLI DTD//EN" "jar://com/iplanet/am/admin/cli/amAdmin.dtd">

    <!-- apply this file by: amadmin -u admin-user -w admin-pwd -t filename.xml -->

    <Requests>

    <SchemaRequests serviceName="iPlanetG11NSettings" SchemaType="Global">

    <AddDefaultValues>

    <AttributeValuePair>

    <Attribute name="sun-identity-g11n-settings-locale-charset-mapping"/>

    <Value>nl|charset=UTF-8</Value>

    </AttributeValuePair>

    </AddDefaultValues>

    </SchemaRequests>

    </Requests>

  5. Save the changes.

ProcedureTo Apply Changes to the Access Manager Administration Console With the amadmin Tool

  1. Change to the Access Manager bin directory.

    # cd AM_BIN/

  2. Run the amadmin tool as follows:

    # ./amadmin -u admin-user -w admin-pwd -t \ /export/am_xml/tmp/amG11nSettings_mod.xml

Adding Localization Resources for a Newly Supported Language

The following information pertains to the example procedures in this section:

ProcedureTo Prepare the Directory Structure

  1. Open a terminal window on the server where an instance of Access Manager is installed (if necessary).

  2. As superuser change to the authentication interface templates base directory.

    # cd AM_INS/web-src/services/config/auth

  3. Create a directory for the top-level organization.

    # mkdir -p example

  4. Copy the contents of the default directory to a new directory for the bookshop sub-realm.

    # cp -rp default example/bookshop

  5. Create a directory to contain the Dutch localization of the bookshop sub-realm.

    # mkdir -p example_nl/bookshop

  6. Copy the default authentication interface templates for the bookshop sub-realm to this new directory.

    # cp -rp example/bookshop/* example_nl/bookshop

ProcedureTo Add Localizing Authentication Interface Files

  1. Change to the created localization directory.

    # cd example_nl/bookshop

  2. Open the Login.jsp file in a text editor.

  3. Navigate to the line that contains this string:

    <body class="LogBdy" onload="placeCursor...>

  4. Below this line, insert the following single line:

    <h5><span style="color: rgb(255,255,255);">Welcome to a Dutch Bookshop organization.</span><br></h5>

  5. Save the changes.

  6. Open the Logout.jsp file in a text editor.

  7. Navigate to the line that contains this string:

    <body class="LogBdy">

  8. Below this line, insert the following single line:

    <h5><span style="color: rgb(255,255,255);">Thank you for visiting our Dutch Bookshop organization.</span><br></h5>

  9. Saves the changes.

  10. Open the LDAP.xml file in a text editor.

  11. Navigate to the line that contains this string:

    <Callbacks length="2" order="1" timeout="120" header="This server uses LDAP Authentication" >

  12. Replace this line with the following single line:

    <Callbacks length="2" order="1" timeout="120" header="This Dutch server uses LDAP Authentication" >

  13. Save the changes.

Applying and Testing Changes

ProcedureTo Redeploy an Access Manager Instance

  1. Open a terminal window on the server where an instance of Access Manager is installed (if necessary).

  2. As superuser change to the Access Manager bin directory.

    # cd AM_BIN/

  3. Copy the amsamplesilent file to a new file titled amsilentredeploy.

  4. Open the amsilentredeploy file in a text editor.

  5. Customize the amsilentredeploy file with the environment details where the Access Manager instance is deployed.

  6. Save the changes to the new amsilentredeploy file.

  7. Run the amconfig tool.

    # ./amconfig -s ./amsilentredeploy

  8. Restart the web container in which the Access Manager instance is currently deployed.

ProcedureTo Test Localizations

  1. Open a browser window (if necessary).

  2. Set the browser language setting to Dutch (nl).

  3. Go to http://host.domain/amserver/UI/Login?org=bookshop.

    A customized Access Manager Administration Console Login page appears.

Generating an MO File in UTF-8 Encoding

This section is not directly related to Access Manager. However, you should perform the following procedures when customizing the Access Manager CLI with a new language.

An MO file is commonly generated with a PO file. Hence, create a PO file and then generate the MO file.

ProcedureTo Create a PO File

  1. Open a terminal window (if necessary).

  2. As superuser create a temporary directory.

    # mkdir /export/am_mo_gen

  3. Change to the created directory.

    # cd /export/am_mo_gen

  4. Create an example.po file.

  5. Open the empty example.po file in a text editor.

  6. Add the following content to the file:

    domain "example"

    msgid "This is an example how to generate a Machine Object file in UTF-8 encoding"

    msgstr "Cet example démontre comment générer un fichier Machine Object encodé avec UTF-8"

  7. Add the charset specification to the bottom of the file, as follows:

    “Content-Type: text/plain; charset=UTF-8\n”

  8. Save the changes.

ProcedureTo Generate an MO File From the Created PO File

  1. Open a terminal window (if necessary).

  2. Go to the directory where a PO file is stored, /export/am_mo_gen in this procedure.

    # cd /export/am_mo_gen

  3. Generate the MO file by using the msgfmt tool.

    # msgfmt -g -o example.mo example.po

Revision History

Version 

Date 

Description of Changes 

1.0 

June 25, 2007 

Initial publication. 

Accessing Sun Resources Online

The docs.sun.com (SM) web site enables you to access Sun technical documentation online. You can browse the docs.sun.com archive or search for a specific book title or subject. Books are available as online files in PDF and HTML formats. Both formats are readable by assistive technologies for users with disabilities.

To access the following Sun resources, go to http://www.sun.com:

Third-Party Web Site References

Third-party URLs are referenced in this document and provide additional, related information.

Note –

Sun is not responsible for the availability of third-party web sites mentioned in this document. Sun does not endorse and is not responsible or liable for any content, advertising, products, or other materials that are available on or through such sites or resources. Sun will not be responsible or liable for any actual or alleged damage or loss caused or alleged to be caused by or in connection with use of or reliance on any such content, goods, or services that are available on or through such sites or resources.

Sun Welcomes Your Comments

Sun is interested in improving its documentation and welcomes your comments and suggestions. To share your comments, go to http://docs.sun.com and click Send Comments. In the online form, provide the full document title and part number. The part number is a 7-digit or 9-digit number that can be found on the book's title page or in the document's URL. For example, the part number of this book is 820-2238.