In this topic
- About localizing add-ins
- Localizing Config.xml
- Localizing .NET resources
- Using Visual Studio and the ArcObjects SDK to build a localized add-in
About localizing add-ins
To localize an add-in to support multiple languages, you need to translate your configuration file (Config.xml) and, if you are using .NET resources, generate satellite assemblies. Once these files have been created, they need to be packaged into your add-in file (.esriAddin).
Localizing Config.xml
Using Visual Studio, or a third-party localization software, translate your configuration file into as many languages as you want. The only elements and attributes you need to translate are captions, descriptions, tips, messages, and help as shown in the following XML example:
[XML] <!-- English -->
<Button
id="Acme_ToggleDockWinBtn"
class="AcmeToggleDockWinBtn"
caption="Show Selection Window"
category="Acme Controls"
image="Images\ToggleDockWinBtn.png"
tip="Shows the ACME Selection Window"
message="Shows the ACME Selection Window">
<Help heading="Add-in button">
The ACME Selection Window displays the current selections count broken down per layer.
</Help>
</Button>
<!-- Chinese -->
<Button
id="Acme_ToggleDockWinBtn"
class="AcmeToggleDockWinBtn"
caption="打开窗å£"
category="æ’件实例"
image="Images\ToggleDockWinBtn.png"
tip="打开显示图层选择的窗å£."
message="打开显示图层选择的窗å£.">
<Help heading="按钮æ’件">点击æ¤æŒ‰é’®æ‰“开显示图层选择的窗å£.</Help>
</Button>
The translated config.xml files must reside at the root level in your add-in archive (.esriAddIn), and the files must adhere to one of the following naming conventions:
- Config.<language>.xml
- Config.<language>-<CountryCode>.xml
The following table shows examples:
|
Config file |
Language or Language-Country |
|
Config.fr.xml |
French |
|
Config.fr-FR.xml |
French-France |
|
Config.fr-CA.xml |
French-Canadian |
The add-in framework automatically detects the locale your Desktop application is currently running under and selects the best matching config file. The selection is accomplished using the following procedure: first the framework searches for a direct match of language and country code, followed by language only. If no good matches are found, the default config.xml file is used.
For example, assume you're running French-Switzerland, and the add-in in question includes the following three files:
- Config.fr-FR.xml
- Config.fr.xml
- Config.xml
In this case, Config.fr.xml would be loaded, because it's the best match. Similarly, if you were running German-Switzerland, and only these files were included, Config.xml would be loaded.
Localizing .NET resources
For add-ins that have additional resources - such as dialog boxes - use the .NET standard satellite assembly model. This model includes using the Microsoft ResourceManager class to load localized resources. For more information on using this class and satellite assemblies in general, consult the Microsoft documentation. As with translated configuration files, satellite assemblies must be packaged into your add-in archive. Satellite assemblies reside in language subfolders under the root Install folder.
The following illustration shows the complete structure of a localized add-in:
Using Visual Studio and the ArcObjects SDK to build a localized add-in
Visual Studio and the ArcObjects .NET software development kit (SDK) make the localization process simple and straightforward. Add your translated configuration files (for example, Config.de.xml) to your Visual Studio project at the root level, next to your default Config.esriaddinx file. See the following screen shot:
The Config.esriaddinx file is renamed Config.xml during packaging.
On the Properties window, change Build Action to AddInContent in each file. This setting specifies that the file should be packaged into the add-in. See the following screen shot:
If you have dialog boxes, such as custom dockable windows, set Localizable to true, then set the target language. For example, the following screen shots show changing the language to German:
At this point modifications to the dialog box will only affect the German version of that dialog box. Translate the appropriate strings. If necessary, move controls to accommodate the locale. Perform this step for each language you want to support. When you build an add-in, Visual Studio automatically generates satellite assemblies for each language you turned on, assuming you made modifications, and the satellite assemblies are automatically packaged into your add-in.