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 help directory. The following shows the help directory structure, if being created for all 10 languages, with English as the default:

The locale setting of the operating system 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. The messages directory contains the .xml file of localizable strings used within the Python toolbox and Python script tools, while the toolboxes directory is used to override the localizable labels for binary toolboxes (custom toolboxes containing model and script tools).

The gp directory stores the .xml files for the side-panel help in the toolbox and the tool. These .xml files are generated from the toolbox's metadata edited in the Item Description context menu by using the createtoolboxsupportfiles function below. The command works on any toolbox.

Note:

Make sure that an alias is set on the toolbox before running the command. The alias is needed to generate the side-panel help files.

arcpy.gp.createtoolboxsupportfiles(<path to .tbx or .pyt>)

This command will generate all the toolbox support files found within the esri folder structure described above. The esri directory is created in the same location as the toolbox pointed to in the input path for the command. The newly generated esri directory structure should be

The side-panel help files are placed into the esri/help/gp directory, the localizable labels file is placed in the esri/help/gp/toolboxes directory, and the ArcPy wrapper for the toolbox is created in the esri/arcpy directory. Additionally, the messages directory needs to be created in the esri/help/gp directory to make the error messages used in the script tools or Python toolboxes localizable and, in case it has not been done yet, the toolboxes directory that stores the toolbox and any supporting Python scripts must be copied into the existing distribution structure. With the messages directory created and the toolboxes directory copied into the esri directory, the structure should be

With the localized properties of the toolboxes and tools in place through the creation of the language-specific .xml files under esri/help/gp and esri/help/gp/toolboxes, one additional .xml file is needed to store the localized error messages used in the script tools or Python toolboxes. Within the esri/help/messages directory, create a new .xml file named messages.xml.

messages.xml

Sample code to create messages.xml:

<Messages>
<Message><ID>unique_string</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

Sample code to edit the execute method in the SamplePythonToolbox.pyt:

def execute(self, parameters, messages):
    """The source code of the tool."""
    messages.AddIDMessage('informative', 'unique_string', os.getenv('username') )
    foo.hello()
    return

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_string 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

To reflect these changes, setup.py needs to be edited. The new setup.py for localization should be

new setup.py for localization

Sample code for setup.py to include localization directories:

from distutils.core import setup
setup(name='foo',
    version='1.0',
    packages=['foo'],
    package_dir={'foo': 'foo'},
    package_data={'foo': ['esri/toolboxes/*.*', 'esri/arcpy/*.*', 'esri/help/gp/*.*', 
        'esri/help/gp/messages/*.*', 'esri/help/gp/toolboxes/*.*']},
    )

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

For the Spanish localization distribution changes to be implemented, the setup.py needs to be edited. The new setup.py for including the Spanish localization should be

new setup.py for Spanish localization

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

from distutils.core import setup
setup(name='foo',
    version='1.0',
    packages=['foo'],
    package_dir={'foo': 'foo'},
    package_data={'foo': ['esri/toolboxes/*.*', 'esri/arcpy/*.*',
        'esri/help/gp/*.*', 'esri/help/gp/messages/*.*',
        'esri/help/gp/toolboxes/*.*', 'esri/help/es/gp/*.*',
        'esri/help/es/gp/messages/*.*', 'esri/help/es/gp/toolboxes/*.*']},
    )

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 10 languages that are supported in ArcGIS can be distributed without the need to create toolboxes and tools for each language.