Internationalization of Python modules

When distributing geoprocessing toolboxes with Python modules, the modules can be customized to support all the languages supported by ArcGIS. 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), 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 within one of the language-specific directories. Each of the gp directories within the language-specific directories store the language-specific metadata .xml files for the side-panel help in the toolbox and the tool. The gp/messages subdirectories contain the .xml files of localizable strings used within the Python toolbox and Python script tools, while the gp/toolboxes subdirectories are used to override the localizable labels for binary toolboxes (custom toolboxes containing model and script tools). These files are generated alongside the ArcPy wrapper using the arcpy.gp.createtoolboxsupportfiles(<path to .tbx or .pyt>) function.

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

The easiest way to create the language-specific subdirectories is to first create the folder structure for the native language (in this case, 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 and esri/help/gp/toolboxes 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. Within the esri/help/messages directory, create a .xml file named messages.xml.

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, the execute method from the SamplePythonToolbox.pyt from extending geoprocessing through Python modules needs to be edited 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 Python ID messages take 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 set the message ID with a company name.

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

Src
├  setup.py
├  Readme.txt
└──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 .xml files can now be edited into any language for toolbox and module support and copied into the respective language directory as outlined above. If the language files are being distributed for Spanish along with English, the directory structure should be as follows:

Src
├  setup.py
├  Readme.txt
└──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

For the Spanish localization distribution changes to be implemented, the setup.py needs to be edited. The new setup.py that includes the Spanish localization should be the following:

New setup.py for Spanish localization

Sample code for setup.py to include Spanish localization directories:

import os 
from setuptools import setup 
 
def read(fname): 
    return open(os.path.join(os.path.dirname(__file__), fname)).read() 
 
setup(name='foo', 
      version='3.0', 
      author='Esri', 
      description=("Example for extending geoprocessing through Python modules"), 
      long_description=read('Readme.txt'), 
      python_requires='~=3.3', 
      packages=['foo'], 
      package_data={'foo':['esri/toolboxes/*',  
                  'esri/arcpy/*', 'esri/help/gp/*',  
                  'esri/help/gp/toolboxes/*', 'esri/help/gp/messages/*',
                  'esri/help/es/gp/*', 'esri/help/es/gp/toolboxes/*', 
                  'esri/help/es/gp/messages/*'] 
                  }, 
      )

Following this process, it is possible to build and distribute a single installable package that will support multiple languages and respond to the locale setting of the operating system in a straightforward .xml-based approach. By extending geoprocessing through Python modules, all languages that are supported in ArcGIS can be distributed without the need to create toolboxes and tools for each language.