Overview of the Maya API
Internationalization Architecture
Maya is an internationalized application. It can support alternate languages in its user interface and it is compatible with localized user environments requiring either single-byte or multi-byte text encodings.
Maya runs in English by default. When Maya is running in an alternate language, user messages, menus, labels and other user interface text are displayed with translated values in place of the default English values.
Read this section if you want to write plug-ins that are compatible within localized user environments and operate correctly with both single and multi-byte text encodings. You can also find information on how to adapt plug-in code and scripts to support one or more alternate user interface languages.
This section gives an overview of the main concepts and features that provide internationalization and localization support in the Maya API. Implementation details and examples are found in subsequent sections.
Internationalization and Localization
There are two main processes involved in preparing plug-ins to run in alternate languages and locales: internationalization and localization.
Internationalization is the process of changing the executable code and scripts so that they can be localized. In the context of plug-ins this mainly involves replacing hard-coded user interface strings with string resources that can be changed to match the user's language choice. String handling code may also require changes to work correctly in all language encodings.
Localization is the process of customizing the plug-in to work in a particular language. For a plug-in this will mainly involve translating the user interface strings and installing them correctly in the plug-in resource path. Once the code is internationalized, it can be localized for one or more target languages.
The Maya application is internationalized using a single-binary strategy. This means that the same executable code can support different languages. All data that varies between user language selections is external to the software itself and is supplied as separate localization-packages. The software itself does not need to be re-built to support a different user language or to run under different codepage settings. This philosophy extends to the internationalization features provided in the Maya API.
Localized user environments will have different locale and codepage (encoding) settings. Maya automatically determines the user language preference and the associated locale and codepage. The manner in which these are determined from user preferences differs across hardware platforms, and is described in the Maya Documentation.
To see what user interface language and codepage Maya is using, type the following commands:
about -uiLanguage;
about -codeset;
To a large extent, proper use of the Maya API classes and methods insulate plug-in code from the locale settings and their implications. It is important however to understand that these settings affect how string data is interpreted and how external interfaces will behave, especially when dealing with multi-byte locales.
The Maya API has its own string class, MString, which is used throughout the API to pass textual data between methods. MString provides methods for manipulating and accessing the string data, which to a large extent insulate the code from any concern about the underlying representation of the string.
The application locale affects the behavior of MString methods that accept or return string data in character (char *) buffers, since the correct data encoding must be used to interpret the character stream. In some cases adaptations to plug-in code accessing or manipulating character buffers will be required to ensure the strings are treated correctly, especially in multi-byte environments. More information about using MString and its methods in a localized environment can be found under String Handling below.
The Maya API has been extended to provide a string resource mechanism for plug-ins. This allows plug-ins to add strings to the Maya String Catalog. Localized values for these strings can be provided for use when Maya is running in an alternate language.
Plug-in string resources can be used in both C++ code and MEL scripts. The plug-in resource architecture is designed so that the default (English) string values are specified directly in the plug-in source code (C++ or script). The default values are "built-in" and are always available.
Localized resource values are provided in external files that are read and loaded into Maya's string catalog when the plug-in is loaded. Adding localized resources does not require rebuilding the plug-in executable.
Localized resources are optional. One advantage to this approach is that plug-ins can be adapted to use string resources but the localization (or translation) of the resources can be deferred until a later time. The localized values will only be used if they are available and match the user's language choice. If localized resources are not found for any reason the plug-in will run as before with the default (built-in) string values.