-
Notifications
You must be signed in to change notification settings - Fork 149
Localization
The Geoportal Server is fully localizable. Localization consists of several activities, each described in this topic.
|
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 localize the web interface.
- 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 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'.
- 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 localized to support that language, the geoportal will default to English. Be sure to enable your selected languages in your internet browser when testing this localization customization.
- 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 ...\geoportal\WEB-INF, and open gpt-faces-config.xml.
- Locate the elements at xpath /faces-config/application/locale-config.
- For each language that will be supported in the geoportal interface, an additional supported-locale element 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.
- 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, 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.
- Restart the geoportal web application for changes to take effect.
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 localizing the webhelp are below:
- Navigate to the geoportal webhelp directory at ...\geoportal\webhelp .
- 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.
- Within your newly named folder, navigate to the \geoportal_10\00t0 directory.
- Within that 00t0 directory, there are several .htm files and graphics files. Translate these files according to your locale.
- 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></title> parameter.
- 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 localization steps, the geoportal will display the localized help system.
Publisher users can request to be notified when the network resource they have registered is synchronized. The notification messages are controlled by notifMessage.xslt in ...\geoportal\WEB-INF\classes\gpt\harvest. Because emails are sent when synchronizing 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 notifMessage.xslt file to read in multiple languages. Steps below describe how to localize the notifMessage.xslt:
- Navigate to ...\geoportal\WEB-INF\classes\gpt\harvest and open notifMessage.xslt in a text editor.
- Edit the text in the body element to read in one or more languages of your choice. Remember not to alter the following placeholders:
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 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:
- Download lucene-3.0.3.zip, 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.
- Unzip the lucene&#45;3.0.3.zip file and navigate to ...\lucene&#45;3.0.3\contrib\analyzers\common.
- In that directory, copy lucene-analyzers-3.0.3.jar and paste it into ...\geoportal\WEB&#45;INF\lib.
- Navigate to ...\geoportal\WEB&#45;INF\classes\gpt\config, and open gpt.xml in a text editor.
- Find the lucene element at xpath /gptConfig/catalog/lucene.
- 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 can be found at the Lucene documentation site. In the example below, a French analyzer is referenced:
analyzerClassName="org.apache.lucene.analysis.fr.FrenchAnalyzer
- IMPORTANT: If the analyzer which you are using requires additional arguments to initialize the analyzer, you will need to write a class to provide those arguments.
- Save the gpt.xml file and restart your geoportal web application for changes to take effect.
This section outlines steps for localizing the Geoportal Clients for ArcGIS. In general, these steps 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".
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
- ArcGIS Explorer 1200 is installed
- ArcGIS Explorer 1200 Developer SDK is installed
- Microsoft Visual Studio 2008 is installed
- You will need to have the source code for Geoportal Clients which you will be localizing
- Verify that you can launch the ArcGIS Desktop and ArcGIS Explorer applications in the language to which you want to localize
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 localize, 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 |
In the charts below, the files that should be localized for each tool and a brief description of the file's localizable interface are shown. Use the guidelines in the Localization section below to localize the files listed for each tool. When you are done localizing according to the guidelines, build the entire solution and run the project in Debug mode to test.
| 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 |
| 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 and Resources.resx | String messages referenced in resx files |
| Filename | Localizable Interface |
|---|---|
| AddIns.xml | 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 CswSearchDockWindow.sln. |
| CSWResources.resx and Resources.resx | String messages referenced in resx files |
| Filename | Localizable Interface |
|---|---|
| Config.esriaddinx | UI container file |
| OpenWMC.resx | UI file: Open WMC user interface |
| StringResources.resx | String messages referenced in resx files |
| StringMessages.resx | String messages referenced in resx files |
Three types of files will be localized: UI container files, UI files, and String files. Each file and its localization steps are described below. Before beginning localization, consult the chart in the Files that will be localized section for the client you are customizing to identify which files should be localized.
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 localizing UI container files are below:
- Browse to the Config.esriaddinx or AddIns.xml file from the project tree in Visual Studio.
- Copy the Config.esriaddinx or AddIns.xml file, and paste it into the solution root.
- You will change the name of the file. The name of the file will 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'.
- 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.
- 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 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.
- Caution: 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.
- For Config.es.xml for the PublishClient.sln project:
- 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.
- Save the file.
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 localizing UI files are below.
Caution: 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 localize the original files according to steps 7 -10 below.
- Browse to UI folder in the project solution.
- 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.
- 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 localization steps.
- Verify that the Localizable attribute beneath the Language attribute is set to True.
- 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.
- 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.
- In the .resx files, there will be two or more columns. Two of the columns will be titled Name and Value.
- 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.
- Update items that are ToolTips, ToolTipText, or Text, localizing them for your locale.
- Save the file.
- Repeat steps 2-12 for all UI Files in the user interface.
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 localizing String files are below.
Caution: 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 localize the original files according to steps 4-5 below.
- Browse to the first String file listed in the table in the Files that will be localized section for the client you are localizing. Copy the file.
- Paste the copy into the same folder from which you copied the original String file.
- Rename the copy to include your chosen locale. For example Copy of StringResources.resx will be renamed StringResources.es.resx.
- 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.
- Save the file.
- Repeat steps 1-5 for each String file for the Client.
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 localizing, 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 |
Note: 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 localized 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:
- Open the CswClient.properties file in a text editor.
- 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
- Save the updated file.
- Copy and paste it to the Destination Location in the chart above.