Localization Process
After the plug-in has been internationalized, string resources can be extracted and sent for translation. It is important to note that the process of localization can be deferred. The plug-in will continue to run with its default resource values if the localized versions are not available.
Plug-in Localization involves the following steps:
The utility script pluginResourceUtil is used to generate a master list of all registered resources for the plug-in.
To run the utility, the name of the plug-in and the name of the output file to generate is specified. The plug-in must be loaded for the resource extraction process to take place; the utility will load the plug-in if it is not already loaded. The extraction process must also be done while Maya is running in the default (English) language. See the Maya documentation for how to override Maya's language setting.
pluginResourceUtil("closestPointOnCurve", "c:/extracted/closestPointOnCurve.pres.mel");The output from the resource extraction process is a file containing a list of commands to set the resources to new values. This master file is not used by the plug-in (the default resource values contained in this file are already available to the plug-in without it). The file is used as the master version of the strings that need to be translated. Only the translated versions of the file are provided with the plug-in.
The complete output file closestPointOnCurve.pres.mel is shown in Example code. A portion of the file is shown below:
// File closestPointOnCurve.pres.mel
// Resources for Plug-in: closestPointOnCurve
//
// ----------------------------
// Registered string resources:
// ----------------------------
setPluginResource( "closestPointOnCurve", "kAETitle", "Closest Point On Curve Attributes");
setPluginResource( "closestPointOnCurve", "kInputCurve", "Input Curve");
setPluginResource( "closestPointOnCurve", "kInvalidType", "Object ^1s has invalid type. Only a curve or its transform can be specified.");
setPluginResource( "closestPointOnCurve", "kNoQueryFlag", "You must specify AT LEAST ONE queryable flag in query mode. Use the `help` command to list all available flags.");
setPluginResource( "closestPointOnCurve", "kNoValidObject", "A curve or its transform node must be specified as a command argument, or using your current selection.");
setPluginResource( "closestPointOnCurve", "kResults", "Results");
The generated file contains an entry for each string resource registered by the plug-in (both C++ and MEL resources). Additionally, if the plug-in has registered nodes, entries for the standardized node and attribute UI display string resources that are used by Maya will be automatically generated (there is no additional registration required for these resources other than correctly registering the node).
The master resource file is translated into another language by editing the string values for each entry in the resource file.
Since the resource file is a MEL text file, its encoding must be appropriate for the locale and platform that it will run on. For example, Japanese translations on Windows platforms will expect CP932, while on Mac OS X they should be UTF-8. Conversion utilities such as iconv can be used for converting file formats if required.
Installation of Localized Resources
The translated resource file must be installed in the correct language-dependent location, so that it will be loaded at runtime. The resource file will have the same name for each language it is translated to; the directory it is located in determines the language it is associated with. The resource file name is passed to loadPluginLanguageResources in the string initialization script. In the example below, the resource file is named closestPointOnCurve.pres.mel.
// Load any localized resources
loadPluginLanguageResources("closestPointOnCurve", "closestPointOnCurve.pres.mel");The loadPluginLanguageResources routine will search for the resource file along the MAYA_PLUG_IN_RESOURCES_PATH.
Typically, plug-ins are installed as modules and their files are installed within a standardized directory structure along the MAYA_MODULE_PATH. The MAYA_PLUG_IN_RESOURCES_PATH will be initialized to include language-specific resource directory entries for each module.
A sample directory hierarchy for a plug-in module is shown below. The resources area contains subdirectories for each available localization. The Japanese resources would be installed into the resources/ja_JP subdirectory. When Maya is running in Japanese, this directory will be added to the MAYA_PLUG_IN_RESOURCES_PATH.
loadPluginLanguageResources does not generate an error at runtime if the resource file is not found. The plug-in simply continues to operate with the default resource values.
The example below shows a sample module hierarchy and the location of Japanese resources for the closestPointOnCurve plug-in.
/SampleModule
/SampleModule/data
/SampleModule/docs
/SampleModule/icons
/SampleModule//modules
/SampleModule/plug-ins
/SampleModule/python
/SampleModule/resources
/SampleModule/resources/ja_JP
/SampleModule/resources/ja_JP/closestPointOnCurve.pres.mel
/SampleModule/scripts
The resource file extraction, translation and installation steps need to be repeated if the plug-in string resources are modified, to keep the localized versions synchronized with the master versions.