Localisation

Overview

The Geoportal is fully localisable. Localisation consists of several activities, each described in this section:

Localise the geoportal web interface

The Geoportal 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 can be viewed by multiple users in multiple languages concurrently. The steps below describe how to localise the web interface.

  1. Identify the correct language code for your localisation customization. When offering localised interfaces, the localisation will be identified by a specific language code. Once you have identified which languages your geoportal 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 localise 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 will always attempt to display its interface in the top-listed language. If the top-listed language is not available because the geoportal has not been localised to support that language, the Geoportal will default to English. Be sure to enable your selected languages in your internet browser when testing this localisation customisation.
  3. Enable additional languages in the Geoportal. In order for a language to be recognized by the Geoportal, you must include a reference to the added language in the gpt-faces-config.xml file. Steps to include the reference are below:
    • Decide which languages to offer and look up the necessary codes as described in the steps above.
    • Navigate to the \\geoportal\WEB-INF directory.
    • Scroll down to the bottom of the file and locate the <application>\<locale-config> tags.
    • For each language that will be supported in the Geoportal interface, an additional <supported-locale> tag should be added. The value of the tag will be the internet code of the language added. Example: <supported-locale>es</supported-locale> for Spanish support.
    • Save the file.
  4. Localise 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 localise the file to another language, translate the strings in the gpt.properties file directly and save the file, overwriting the original. The default file will now render the interface in the new language. To offer the Geoportal interface in multiple languages, do the following:
    • Decide which languages to offer and look up the necessary codes as described in the steps above.
    • Copy the gpt.properties file to a new file, saving it with a filename that has an underscore and the language code appended after gpt. For example, for a French file the filename would be gpt_fr.properties. For a Chilean Spanish file, the filename would be gpt_es-cl.properties.
    • Open the newly created properties file in a text editor and translate into its respective language.
    • 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 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 deployment, the Geoportal will display the resource strings from the matching language file, and thereby display a localised interface.

Localise the geoportal webhelp

The Geoportal offers a context-sensitive help system that links to the webhelp deployed with the Geoportal. If a user needs help while using the Geoportal, he/she can click the Help link at the top of any page, and will be directed to that page's help information in the webhelp. Steps for localising the webhelp are below:

  1. Configure the geoportal to reference your customized help instead of the Esri-hosted webhelp. Instructions for this are available at the 37450 Knowledge Base article.
  2. Navigate to the geoportal webhelp directory at \\geoportal\webhelp .
  3. Similar to how you renamed the gpt.properties file to reference a language code, you will need to create a directory within the \\geoportal\webhelp folder with your two or four letter language code. Do this by copying the en folder from \\geoportal\webhelp and pasting it in the same \\geoportal\webhelp directory. Then rename your copied folder according to your two or four letter language code.
  4. Within your newly named folder, navigate to the geoportal_10\00t0 directory.
  5. Within that 00t0 directory, there are several .htm files and graphics files.Translate these files according to your locale.
  6. Navigate one folder up to the \\geoportal_10 folder, and open the index.html file in a text editor. Translate the text in the <title> parameter.
  7. After the files have been translated, all files should be saved and the geoportal web application restarted. With the newly translated files available, if a user sets the primary language in their browser to a language to which you've enabled through these localisation steps, the Geoportal will display the localised help system.

Localise Mail Messages

Publisher users can request to be notified when the network resource they have registered is synchronised. The notification messages are controlled by the notifMessage.xslt file in the \\geoportal\WEB-INF\classes\gpt\harvest folder. Because emails are sent when synchronising is instigated and not at the end user's request, there is not a way for the Geoportal 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. Steps below describe how to localise the notifMessage.xslt:

  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:
    • <xsl:value-of select="repositoryName"/> name of registered network resource
    • <xsl:value-of select="eventData"/> date of synchronisation
    • <a href="{reportLink}"><xsl:value-of select="reportLink"/> link to the synchronisation report
  3. Save the notifMessage.xslt file.

Localise the geoportal's lucene search engine

The Geoportal comes with the Apache Lucene search engine configured for English by default. To enhance performance of the lucene index if your geoportal 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. To change the default language of the lucene engine used in your geoportal deployment, do the following:

  1. Download the lucene-3.0.1.zip file, which can be found at the Apache lucene archiving location (http://archive.apache.org/dist/lucene/java). This file is the lucene archive that corresponds to the lucene version implemented by the Geoportal version 10.
  2. Unzip the lucene-3.0.1.zip file and navigate 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. Navigate 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 web application for changes to take effect.
TipTip:

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.

Localise Geoportal Clients

This section outlines steps for localising the Geoportal Clients. In general, these steps follow the guidelines found in the ArcGIS Desktop Developer Help for Localising Add-Ins.

CautionCaution:

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 localisation. In this Spanish example, filenames have the Spanish language code "es".

Prerequisites for localising the Geoportal Clients are:

  • For ArcMap and ArcCatalog Geoportal Clients:
    • ArcGIS Desktop 10.0 is installed
    • ArcGIS Desktop Developer SDK for .NET applications is installed
    • Microsoft Visual Studio 2010 is installed
  • For ArcGIS Explorer Geoportal Clients:
    • ArcGIS Explorer 1200 is installed
    • ArcGIS Explorer 1200 Developer SDK is installed
    • Microsoft Visual Studio 2008 is installed
  • You have the source code for Geoportal Clients which you will be localising
  • You can launch the ArcGIS Desktop and ArcGIS Explorer applications in the language to which you want to localise
Steps for Localising Geoportal Clients are described in the sections below. It is important to do all steps in the order described.
  1. Opening the project
  2. Files that will be localised
  3. Localisation instructions
  4. Copy properties files

Opening the project

Open Microsoft Visual Studio, and go to the File menu. Select Open and then Project/Solution. Then browse to the solution file for the client you want to localise, as per chart below.

Client name

Solution filename

Publish Client

PublishClient.sln

CSW Clients for ArcGIS Desktop

CSWSearch.sln

CSW Clients for ArcGIS Explorer

CSWSearchDockWindow.sln

WMC Client

WMCOpener.sln

Files that will be localised

In the charts below, the files that should be localised for each tool and a brief description of the file's localisable interface are shown. Use the guidelines in the Localisation section below to localise the files listed for each tool. When you are done localising according to the guidelines, build the entire solution and run the project in Debug mode to test.

Publish Client

Filename

Localisable 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

Localisable 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.

NoteNote:

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

CswClient for ArcGIS Explorer

Filename

Localisable Interface

AddIns.xml Resources.resx String messages referenced in resx files

UI container file

CswSearchDockableWindow.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.

NoteNote:

this file is found in the CSWClient project, not the UI folder in the CswSearchDockWindow.sln.

CSWResources.resx

Resources.resx

String messages referenced in resx files

WMC Client

Filename

Localisable Interface

Config.esriaddinx

UI container file

OpenWMC.resx

UI file: Open WMC user interface

StringResources.resx

String messages referenced in resx files

Localisation instructions

Three types of files will be localised: UI container files, UI files, and String files. Each file and its localisation steps are described below. Before beginning localisation, consult the chart in the Files that will be localised section for the client you are customising to identify which files should be localised.

  • UI container file localisation:UI container files are found at the root of the project solution. These files define the container - the window housing the client - for the user interface. They will be named either Config.esriaddinx for ArcGIS Desktop clients, or AddIns.xml for ArcGIS Explorer clients. Steps for localising UI container files are below:
    1. Browse to the Config.esriaddinx or AddIns.xml file from the project tree in Visual Studio.
    2. Copy the Config.esriaddinx or AddIns.xml file, and paste it into the solution root.
    3. You will change the name of the file. The name of the file will include the language code for which you are localiszing. 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. Localise 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 AddIns.es.xml for the CSWSearchDockWindow.sln project:
        • Update the description and groupCaption attributes in the ExplorerAddIns> element.
        • Update the caption and tooltip attributes in the ExplorerAddIns>dockWindow> element.
          CautionCaution:

          After you have made these changes to the AddIns.es.xml file, copy the entire contents back into the original AddIns.xml file, save it, and delete the AddIns.es.xml file.

      • 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.
      NoteNote:

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

    7. Save the file.
  • UI file localisation: 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 an '.resx' extension. They define the actual form 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. Steps for localising UI files are below.
    CautionCaution:

    For the UI files in the CSWSearchDockWindow.sln project (CSW Clients for ArcGIS Explorer), you will not need to create copies of the original files or change the original file names. Simply localise the original files according to steps 7 -10 below.

    1. Browse to UI folder in the project solution.
    2. Double click on the parent .cs node for the .resx file you are going to localise. Note that the form's properties are displayed in the Properties window.
    3. In the Properties window, scroll down to the Language attribute. Change the Language from Default to the desired locale corresponding to the one you specified for your UI container file in container file localisation steps.
    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. Verify that the new file has the same information as the corresponding .resx file under the form. 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. If not, then copy the text from the old file into the new one so they match.
    7. In the .resx files, there will be two or more columns. Two of the columns will be titled Name and Value.
    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-localisable tool functionality, or are referenced by strings in the String files.
    9. Update items that are ToolTips, ToolTipText, or Text, localising them for your locale.
    10. Save the file.
    11. Repeat steps 2-12 for all UI Files in the user interface.
  • String message file localisation: 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. Steps for localising String files are below.
    CautionCaution:

    For the String files in the CSWSearchDockWindow.sln project (CSW Clients for ArcGIS Explorer), you will not need to create copies of the original files or change the original file names. Simply localise the original files according to steps 4-5 below.

    1. Browse to the first String file listed in the table in the Files that will be localised section for the client you are localising. 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 desire. 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-5 for each String file for the client.

Copy properties files

When the Geoportal 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 Debug mode.

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 localising, as per the table below.

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

CSW Clients for ArcGIS Explorer

CswClient.properties

\\CSWCLIENTS\Common\DotNet\Src\CswClient

\\ArcGIS Explorer\Bin

WMC Client

WMCOpener.properties

\\WMCOPENER

\\WMCOPENER\bin\Debug

NoteNote:

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 by default be set to C:\\Program Files\\ESRI\\Portal\\CswClients\\Data. 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 localised version, you need to point the dataFolder parameter in the properties file to the Data folder in your build structure. Steps for how to update the dataFolder parameter are below:

  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 filepath would be changed to C:\\CSWClients\\Common\\Data
  3. Save the updated file.
  4. Copy and paste it to the Destination Location in the chart above.

After you have localised the UI container files, UI files, and String messages for the Geoportal Client you are localising, build the Solution. Then run the solution in Debug mode to test.

1/29/2014