Internationalization of geoprocessing modules

When creating geoprocessing modules, the modules can be customized to support all the languages supported by ArcGIS Pro. The help and support files for these supported languages are stored in the esri/help directory. The following shows a subset of the help directory structure, with the first five languages (in alphabetical order, after English as the default) supported by ArcGIS Pro:

help
├──gp (English - Default)
│   ├──messages
│   └──toolboxes
├──ar (Arabic)
│   └──gp
│       ├──messages
│       └──toolboxes
├──cs (Czech)
│   └──gp
│       ├──messages
│       └──toolboxes
├──de (German)
│   └──gp
│       ├──messages
│       └──toolboxes
└──es (Spanish)
    └──gp
        ├──messages
        └──toolboxes

The full language name in parentheses is not part of the folder name and should be omitted. Additional languages are fi (Finnish), fr (French), he (Hebrew), it (Italian), ja (Japanese), ko (Korean), pl (Polish), pt-BR (Portugese - Brazil), ru (Russian), sv (Swedish), tr (Turkish), uk (Ukranian), zh-CN (Chinese - Simplified), and zh-TW (Chinese - Traditional).

The language setting of ArcGIS Pro is used to determine which directory is searched initially. The top-level gp directory is used for the English language and is the default when the file being searched is not found in one of the language-specific directories. Each of the gp directories in the language-specific directories stores the language-specific metadata .xml files for the ScreenTip help in the tool. The gp/messages subdirectories contain the .xml files of localizable strings used in the Python toolbox and Python script tools, while the gp/toolboxes subdirectory is used to override the localizable labels for binary toolboxes (custom toolboxes containing model and script tools). These files are generated using the arcpy.gp.createtoolboxsupportfiles(<path to toolbox>) function.

gp
 ├  SamplePythonToolbox_toolbox.xml
 ├  SampleTool_SamplePythonToolbox.xml
 ├──messages 
 └──toolboxes
     └  SamplePythonToolbox.xml

The most straightforward way to create the language-specific subdirectories is to first create the folder structure for the English gp directory. With the localized properties of the toolboxes and tools in place through the creation of the .xml files under esri/help/gp following extending geoprocessing through Python modules, one additional .xml file is needed to store the localized messages used in the script tools or Python toolboxes. In the esri/help/messages directory, create a messages.xml file.

messages.xml

The following is sample code to create messages.xml:

<Messages>
<Message><ID>unique_id</ID><Description>%1, welcome to the sample tool</Description></Message>
</Messages>

To reflect this change, edit the execute method from the SamplePythonToolbox.pyt file to use the AddIDMessage method instead of AddMessage. The new execute method should be as follows:

Python toolbox execute method

Sample code of the SamplePythonToolbox.pyt execute method for using the AddIDMessage method:

def execute(self, parameters, messages):
        """The source code of the tool."""
        result = foo.bar.hello()
        messages.AddIDMessage("INFORMATIVE", "unique_id", result)
        parameters[0].value = result

The AddIDMessage method provides an effective way of accessing the external messages stored in the messages.xml file in the esri/help/messages directory. In this case, it uses the message marked with the unique_id ID. The message can be any string. The message ID can be either an integer or a string; the integers reference Esri messages, and the strings should be used by third-party developers or users. Since it is easier to make strings unique, one suggestion is to prefix the message ID with a company name.

With these changes in place, the new distribution directory structure should be as follows:

Src
└──foo
    ├  __init__.py 
    ├  bar.py
    └──esri
        ├──arcpy
        │   └  SamplePythonToolbox.py
        ├──help
        │   └──gp
        │       ├  SamplePythonToolbox_toolbox.xml
        │       ├  SampleTool_SamplePythonToolbox.xml
        │       ├──messages
        │       │   └  messages.xml
        │       └──toolboxes
        │           └  SamplePythonToolbox.xml
        └──toolboxes
            ├  SamplePythonToolbox.pyt
            ├  SamplePythonToolbox.pyt.xml
            └  SamplePythonToolbox.SampleTool.pyt.xml

The gp folder can now be copied into the respective language directory as outlined above and the .xml files can be edited into any supported language. For example, if the language files are being distributed for Spanish along with English, the directory structure should be as follows:

Src
└──foo
    ├  __init__.py 
    ├  bar.py
    └──esri
        ├──arcpy
        │   └  SamplePythonToolbox.py
        ├──help
        │   ├──es
        │   │   └──gp
        │   │       ├  SamplePythonToolbox_toolbox.xml
        │   │       ├  SampleTool_SamplePythonToolbox.xml
        │   │       ├──messages
        │   │       │   └  messages.xml
        │   │       └──toolboxes
        │   │           └  SamplePythonToolbox.xml
        │   └──gp
        │       ├  SamplePythonToolbox_toolbox.xml
        │       ├  SampleTool_SamplePythonToolbox.xml
        │       ├──messages
        │       │   └  messages.xml
        │       └──toolboxes
        │           └  SamplePythonToolbox.xml
        └──toolboxes
            ├  SamplePythonToolbox.pyt
            ├  SamplePythonToolbox.pyt.xml
            └  SamplePythonToolbox.SampleTool.pyt.xml

Following this process, a single installable package can be built and distributed that will support multiple languages using an XML-based approach that is responsive to the locale setting of the operating system. By extending geoprocessing through Python modules, all languages that are supported in ArcGIS Pro can be distributed without the need to create toolboxes and tools for each language. Once internationalizing of the toolbox is completed, the geoprocessing module is ready for distribution.