Localizing Esri Geoportal Server

Esri Geoportal Server is fully localizable. The following can be localized: Geoportal Server web interface, email messages, lucene search engine, and clients.

Localizing the Geoportal Server web interface

The Geoportal Server web interface can be displayed in any language, including multi-byte and right-to-left languages. The language chosen for display is selected from the settings in a user's Internet browser and does not depend on any server-side variables. This means that a single instance of the Geoportal Server can be viewed by multiple users in multiple languages concurrently.

1. Identify the correct language code for your localization customization.

   When offering localized interfaces, the localization will be identified by a specific language code. Once you have identified which languages your Geoportal Server will support, look up the standard 2-letter internet language code for your chosen language(s). For example, French is referenced by fr, German by de and Spanish by es. If you would like to localize for a particular flavor of a language, for example Canadian French, or Chilean Spanish, the internet language code will consist of 4 letters. The first two designate the language, and the latter two, the country. These two codes are then separated by a hyphen. For example Canadian French is fr-ca and Chilean Spanish is es-cl.

2. Set up your browser for multiple languages.

   Internet browsers have a setting that allows users to choose the languages - in a specified order - in which they prefer to view web page content. The Geoportal Server will always attempt to display its interface in the top-listed language. If the top-listed language is not available because the Geoportal Server has not been localized to support that language, the Geoportal Server will default to English. Be sure to enable your selected languages in your internet browser when testing this localization customisation.

3. Enable additional languages in the Geoportal Server.

   For a language to be recognized by the Geoportal Server, you must include a reference to the added language in the gpt-faces-config.xml file. Perform the following steps to include the reference.

   1. Decide which languages to offer and look up the necessary codes as described in the previous steps.
   2. Navigate to the \\geoportal\WEB-INF directory.
   3. Scroll to the bottom of the file and locate the <application>\<locale-config> tags.
   4. Add an additional <supported-locale> tag for each language that will be supported in the Geoportal Server interface.

      The value of the tag will be the internet code of the language added. Example: <supported-locale>es</supported-locale> for Spanish support.

   5. Save the file.
4. Localize the interface text.

   By default, strings displayed in the interface are referenced from the gpt.properties file found in \\geoportal\WEB-INF\classes\gpt\resources. To permanently localize the file to another language, translate the strings in the gpt.properties file directly and save the file, overriding the original. The default file will now render the interface in the new language. To offer the Geoportal Server interface in multiple languages, do the following:

   1. Decide which languages to offer and look up the necessary codes as described in the previous steps.
   2. Copy the gpt.properties file to a new file, saving it with a file name that has an underscore and the language code appended after gpt. For example, for a French file, the name would be gpt_fr.properties. For a Chilean Spanish file, the name would be gpt_es-cl.properties.
   3. Open the newly created properties file in a text editor and translate into its respective language.
   4. Save the translated file and exit.

   If the language being translated uses non-Latin1 characters, the native2ascii utility can be used to properly encode your newly created file.

5. Restart the Geoportal Server web application for changes to take effect.

With the newly translated files available, if a user sets the primary language in their browser to a language that matches one of the files available in your Geoportal Server deployment, the Geoportal Server will display the resource strings from the matching language file, and thereby display a localized interface.

Localizing mail messages

Publisher users can request to be notified when the network resource they have registered is synchronized. The notification messages are controlled by the notifMessage.xslt file in the \\geoportal\WEB-INF\classes\gpt\harvest folder. Because emails are sent when synchronizing is instigated and not at the end user's request, there is not a way for the Geoportal Server to determine in what language the end user prefers to receive email. Therefore, if your organization will be notifying publisher users that speak a variety of languages, it will be important to edit the message in the notfiMessage.xslt file to read in multiple languages. The following steps describe how to localize the file.

1. Navigate to the \\geoportal\WEB-INF\classes\gpt\harvest and open the notifMessage.xslt file in a text editor.
2. Edit the text within the <body> tags to read in one or more languages of your choice.

   Remember not to alter the following placeholders:

   • Name of registered network resource—<xsl:value-of select="repositoryName"/>
   • Date of synchronization—<xsl:value-of select="eventData"/>
   • Link to the synchronization report—<a href="{reportLink}"><xsl:value-of select="reportLink"/>

3. Save the notifMessage.xslt file.

Localizing the Geoportal Server's lucene search engine

The Geoportal Server comes with the Apache Lucene search engine configured for English by default. To enhance performance of the lucene index if your Geoportal Server is using another language, you can use an analyzer that was created for that language. Visit the lucene contrib-analyzers API for Javadoc for optional analyzers.

Tip:

It is also possible to create your own analyzer class to include your specific filters. Once you have created and compiled your own analyzer, you can paste it in the \\geoportal\WEB-INF\lib directory. Then, update the gpt.xml file's <lucene> element to reference the analyzer class that you compiled.

To change the default language of the lucene engine used in your Geoportal Server deployment, do the following:

1. Download the lucene-3.0.1.zip file, which can be found at the Apache lucene archiving location.

   This file is the lucene archive that corresponds to the lucene version implemented by the Geoportal Server.

2. Unzip the lucene-3.0.1.zip file and browse to the \\lucene-3.0.1\contrib\analyzers\common directory.
3. In that directory, copy the lucene-analyzers-3.0.1.jar and paste it into the \\geoportal\WEB-INF\lib directory.
4. Browse to the \\geoportal\WEB-INF\classes\gpt\config directory, and open the gpt.xml file in a text editor.
5. Find the <lucene>element.
6. Change the attribute for analyzerClassName to reference the analyzer class that corresponds to the analyzer you want to use.

   Javadoc for pre-configured analyzer classes are described at http://lucene.apache.org/java/3_0_1/api/contrib-analyzers/index.html.

   In the example below, a French analyzer is referenced:

   analyzerClassName="org.apache.lucene.analysis.fr.FrenchAnalyzer

7. Save the gpt.xml file and restart your Geoportal Server web application for changes to take effect.

Localizing Geoportal Server clients

The steps for localizing the Geoportal Server clients follow the guidelines found in the ArcGIS Desktop Developer help for localizing add-ins.

Caution:

The instructions in this guide are shown for a Spanish customization. When following instructions in this section, update the filenames to reflect the language of localization. In this Spanish example, filenames have the Spanish language code "es".

Prerequisites for localizing the Geoportal Server clients

• For ArcMap and ArcCatalog Geoportal Server clients:
  • ArcGIS Desktop is installed
  • ArcGIS Desktop Developer SDK for .NET applications is installed
  • Microsoft Visual Studio 2010 is installed
• You have the source code for Geoportal Server clients that you will be localizing
• You can launch the ArcGIS Desktop applications in the language to which you want to localize

The steps for localizing Geoportal Server clients are described in the following sections. It is important to do all steps in the order described.

1. Opening the project
2. Files that will be localized
3. Localizing files
4. Copying properties files

Opening the project

You need to access the solution file for the client you want to localize.

1. Start Microsoft Visual Studio.
2. Click File > Open > Project/Solution.
3. Then browse to the solution file for the client you want to localize, per the table below.

   Client name	Solution filename
   Publish Client	PublishClient.sln
   CSW Clients for ArcGIS Desktop	CSWSearch.sln
   WMC Client	WMCOpener.sln

Files that will be localized

In the following tables, the files that should be localized for each tool and a brief description of the file's localizable interface are described. Use the guidelines in the Localizing files section to localize the files listed for each tool.

Publish Client

Filename	Localizable Interface
Config.esriaddinx	UI container file
FormMessageBox.resx	UI file: Popup message user interface
PublishForm.resx	UI file: Publish Client input user interface
StringMessages.resx	String messages referenced in resx files

CswClient for ArcMap

Filename	Localizable Interface
Config.esriaddinx	UI container file
CswClientDockableWindow.resx	UI file: CSW Client input user interface
FormMessageBox.resx	UI file: Popup message user interface
FormViewMetadata.resx	UI file: Window for View Metadata user interface
PromptCredentials.resx	UI file: interface for entering credentials to connect to a secure service. Note: this file is found in the CSWClient project, not the UI folder in the CSWSearch.sln.
StringResources.resx Resources.resx	String messages referenced in resx files

WMC Client

Filename	Localizable Interface
Config.esriaddinx	UI container file
OpenWMC.resx	UI file: Open WMC user interface
StringResources.resx	String messages referenced in resx files

Localizing files

Three types of files need to be localized: UI container files, UI files, and string files. Before beginning localization, consult the tables in the Files that will be localized section for the client you are customizing to identify which files should be localized.

Localizing UI container files

UI container files are found at the root of the project solution. These files define the container - the window or dialog box housing the client - for the user interface. They will be named Config.esriaddinx for ArcGIS Desktop clients.

1. Browse to the Config.esriaddinx or AddIns.xml file from the project tree in Visual Studio.
2. Copy the Config.esriaddinx or AddIns.xmlfile, and paste it into the solution root.
3. Change the name of the file.

   The name of the file needs to include the language code for which you are localizing. The form of the name will be Config.xx.xml, where xx is your language code. For our Spanish example, Copy of Config.esriaddinx should be changed to Config.es.xml.

4. Open the newly named file and verify that the new Config.es.xml file has the same information as the old Config.esriaddinx file; if not, then copy the text from the old Config.esriaddinx file into the new Config.es.xml one so they match.
5. Localize the following XML attributes in the new file according to the locale.

   For Config.es.xml for the PublishClient.sln project	Update the caption and tip attributes in the Add-In>ArcMap>Commands>Button>element. Update the caption and tip attributes in the Add-In>ArcCatalog>Commands>Button>element.
   For Config.es.xml for the CSWSearch.sln project	Update the caption and tip attributes in the Add-In>ArcMap>Commands>Button>element. Update the caption attribute in the Add-In>ArcMap>DockableWindows>DockableWindow>element.
   For Config.es.xml for the WMCOpener.sln project	Update the caption and tip attributes in the Add-In>ArcMap>Commands>Button>element.

6. In the Properties window for the file, change the Build Action from Embedded Resource to AddInContent.

   Note:

   For the CSWSearchDockWindow.sln project, there is not an AddInContent option. Leave the Build Action as Embedded Resource.

7. Save the file.

Localizing UI files

UI files are usually found in the UI folder in the project solution, and are visible when you expand the form (.cs extension) that contains them. These files have a .resx extension. They define the actual dialog box interface of the clients that the user sees, and also text that is displayed in message windows. The UI files work with the string files to associate text with the user interface. For example, a UI file might have a reference to a string managed in a string file.

1. Browse to the UI folder in the project solution.
2. Double click on the parent .cs node for the .resx file you are going to localize.

   Note that the form's properties are displayed in the Properties window.

3. In the Properties window, scroll to the Language attribute and change the it from Default to the locale corresponding to the one you specified for your UI container file.
4. Verify that the Localisable attribute beneath the Language attribute is set to True.
5. Expand the node for the .cs form in the solution tree.

   Note that a new file has been created, and its name automatically includes the language code corresponding to the Language attribute of the form file.

6. Double click on the new .resx file to open it.
7. Verify that the new file has the same information as the corresponding .resx file under the form; if not, then copy the text from the old file into the new one so that they match.

   For example, a newly generated FormMessageBox.es.resx file should contain the same number of columns, rows, and have the same text in the cells as the FormMessageBox.resx file.

8. In the newly generated .resx file, find the Name and Value columns. Do not change information in the Name column. Update the information in the Value column only if the Name ends in a ToolTip, ToolTipText, or Text suffix.

   All other items are either related to non-localizable tool functionality, or are referenced by strings in the string files.

9. Localize the following items for your locale: ToolTips, ToolTipText, or Text.
10. Save the file.
11. Repeat steps 1-10 for all UI Files in the user interface.

Localizing string message files

String files are found in the root of the project solution, except for in the CSWSearchDockWindow.sln project; they are found in the folder titled Resources. The string files, like the UI files, also have a .resx extension. They define strings used in the forms defined by the UI files and other parts of the tool. Each client has one or two string files.

1. Browse to the first string file listed in the table in the Files that will be localized section for the client you are localizing, and copy the file.
2. Paste the copy into the same folder from which you copied the original string file.
3. Rename the copy to include your chosen locale.

   For example Copy of StringResources.resx will be renamed StringResources.es.resx.

4. Open the file and update the items in the Value column according to your locale.

   Unlike the UI files, you can update every item listed if you want. However, like the UI files, it is important that you do not change the information in the Name column.

5. Save the file.
6. Repeat steps 1 through 5 for each string file for the client.

Copying properties files

When the Geoportal Server clients are installed using compiled code and the installer, a properties file that is called at runtime is installed for each tool. Because you have not run the installer but are testing with source code, you will need to copy the properties file into its correct location before testing in the debug mode.

Before you copy the properties file for the CSWSearch.sln and CSWSearchDockWindow.sln projects, you will need to edit its dataFolder parameter. The dataFolder will be set to C:\\Program Files\\ESRI\\Portal\\CswClients\\Data by default. This default location tells the CSW Clients where to look for the CSW Profiles, and when the client is installed via the windows installer, the data folder is created in a specified directory (C:\Program Files\ESRI\Portal\CSWClients by default). Because this location for the Data folder does not yet exist when you are building a localized version, you need to point the dataFolder parameter in the properties file to the data folder in your build structure.

1. Open the CswClient.properties file in a text editor.
2. Change the dataFolder location from C:\\Program Files\\ESRI\\Portal\\CswClients\\Data to the location that matches your build structure.

   For example, if you are working with your CSW Client source code stored in a CSWClients folder on your C drive, the file path would be changed to C:\\CSWClients\\Common\\Data

3. Save the updated file.
4. Copy the properties file listed in the Filename column from the location in the Initial Location column to the location in the Destination location column for the client you are localizing, as per the following table.

   Client	Filename	Initial Location	Destination Location
   Publish Client	PublishClient.properties	\\PUBLISHCLIENT	\\PUBLISHCLIENT\bin\Debug
   CSW Clients for ArcGIS Desktop	CswClient.properties	\\CSWCLIENTS\Common\DotNet\Src\CswClient	\\CSWCLIENTS\ArcMap\Src\CswSearch\bin\Debug
   WMC Client	WMCOpener.properties	\\WMCOPENER	\\WMCOPENER\bin\Debug

After you have localized the UI container files, UI files, and string messages for the Geoportal Server client you are localizing, build the solution. Then run the solution in the debug mode to test.