How to create a locale-specific add-in

Summary
This topic describes the different ways to create a locale-specific add-in.
The techniques described in this topic are appropriate for add-ins that contain or use locale-specific strings, images, or other information that must be localized for a specific language or region.

In this topic

Locale-specific resources

To localize add-ins that use standard project resources, use the .NET standard satellite assembly model, in which locale-specific satellite assemblies are created from locale-specific resource files included in a project. For more information on using this class, as well as information on satellite assemblies in general, see the Microsoft documentation on globalizing and localizing applications. For an example of using satellite assemblies with localized resources in ArcGIS Explorer, see Locale-specific ComboBox.
As with translated configuration files, satellite assemblies must be packaged into your add-in file. Satellite assemblies must reside in language subfolders under the add-in folder. To accomplish this, follow these steps:
  1. Include the compiled satellite assemblies in your project file in the appropriately named subfolders by first building the project, then copying the locale-specific subfolders (including the satellite assemblies) to the project directory.
  2. Set the build action of the satellite assemblies in the project to content, which specifies that the file be included in the add-in .eaz file when it's created or updated.
  3. Update the satellite assemblies when the project is recompiled, but before the add-in .eaz file is created, by using an MSBuild Copy task. The following code sample is an example of an MSBuild Copy task in a project file used to copy a German (Germany) satellite assembly:
[XML] 
<Target Name="AfterBuild">
  <Copy
    SourceFiles="$(TargetDir)de-DE\LocaleSpecificCS.resources.dll"
    DestinationFolder="de-DE"
    ContinueOnError="true"
    SkipUnchangedFiles="false"/>
  <MakeEaz
    InputAssembly="$(TargetPath)"
    AddinsXml="Addins.xml"
    Content="@(Content)"
    References="@(Reference)"
    OutputPath="$(EazPath)"/>
</Target>
Refer to the Locale-specific ComboBox sample project files for an example of implementing these steps.

Localizable property

If an add-in includes dockable windows or other dialog boxes, you can use the Localizable property to generate locale-specific resources by performing the following steps:
  1. After the dialog box is complete in the default language, set the Localizable property to true, then set the target language. At this point, modifications to the dialog box will only affect the specified version of that dialog box.
  2. Translate the appropriate strings. If necessary, move controls to accommodate the locale. Perform this step for each locale.
When the add-in is subsequently built, Visual Studio automatically generates satellite assemblies for each language you turned on. You can then include the satellite assemblies in the add-in .eaz file using the steps previously described for packaging the satellite assemblies.

Locale-specific Addins.xml

ArcGIS Explorer uses strings from the Addins.xml manifest file to display captions and ToolTips for add-in controls, as well as group captions, descriptions, and publisher information for add-in files.
If these strings need to be localized, you must create a separate add-in project for each locale using appropriate locale-specific strings in each case. In this scenario, share the code files between the locale-specific projects, using the locale-specific resources technique described previously for any internal resource localization.

MSBuild tasks

MSBuild is the configurable build platform of Visual Studio. MSBuild tasks are operations that are performed during the build process. The Visual Studio tools for ArcGIS Explorer use the MSBuild platform to create and verify add-in .eaz files when you build an add-in project in Visual Studio. For more information, see Building and verifying add-in projects.
Visual Studio does not provide a user interface for working with MSBuild tasks; however, you can use either of the following approaches to manually edit a project file (*.csproj, *.vbproj) if required:
  • In Visual Studio Solution Explorer, perform the following steps:
    1. Right-click the project and choose Unload Project.
    2. Right-click the project again and choose Edit <project file name>. This opens the project file in an Extensible Markup Language (XML) editing view in Visual Studio.
    3. Close the project file window and choose Reload Project from the project context menu. This reloads the project using the standard project view.
  • Open an add-in project file in a text editor such as Notepad.
Take care when editing project files, as incorrect edits can prevent your project from loading, building, or compiling correctly. Always backup your files before manually editing a project file.


See Also:

Sample: Locale-specific ComboBox
MSBuild Overview