Electronic Ink
TECH NOTES   XTRAS PROGRAMMING   GLOBAL XTRAS  
Home
Products
Tech Notes
Contact Us

Creating Globalized and Localized Xtras

Just because you never intend to publish your Xtra in languages such as French, German, Japanese, or Urdu doesn't mean that your Xtra should break when your users create Director presentations in these languages. The main reason? Because Director itself won't break when used to create presentations with text in any of these languages. Director is what's known in the industry jargon as a globalized program. This means that regardless of the language that you see in the program's menus, text messages, and so on, the software is capable of creating presentations whose text can be in any language on the planet. (Or at least any language deemed important enough by Apple and Microsoft to create localized system software for it.)

The flipside of globalization is localization, or the translation of the menu items, dialogs, text messages, etc., of a program into another language. Director is globalized software that has also been localized in English, French, German, and Japanese. The important thing to note is that there's no difference in the core code of Director among these localized versions: you can use the German version to create presentations in Japanese, and vice versa. Both Mac and Windows versions of Director in all localized forms (including the English version) fully support strings that use MBCS (multi-byte character sets) when they are running on a version of MacOS or Windows that is multibyte-enabled. And your Xtras should do the same.

About MBCS

In MBCS, not every character in a text string is represented by a single byte. Some characters have a "flag" bit in them, which signifies that that character and the one following it should be read as a single 16-bit value. This 16-bit value represents a single character on screen, such as a symbol in Japanese Kanji. So in multi-byte script systems, one-byte and two-byte characters are mixed together within character strings. This technique is the standard way that Macintosh and Windows operating systems implement multi-byte characters.

But what about the "Unicode" standard, in which every character in every known language on the planet is assigned its very own unique 16-bit value? Very surprisingly, neither the MacOS nor Windows directly support the Unicode standard, but both have just sort of hacked their own multi-byte systems together. It is possible to write Unicode software applications for these platforms, but you'll get no help from the operating systems themselves in doing so. Fortunately, the two multi-byte systems on MacOS and Windows are at least compatible in that they use the same multi-byte codes (for Japanese text at least) on both platforms without any messy character re-mapping.

Director, Xtras, and MBCS

When running on a multi-byte enabled operating system, Xtras can both get and set MBCS strings from Director intact. Director supports MBCS within string variables and within text and text field cast members. Your Xtra can also pass Director MBCS strings for things such as Lingo Xtras' message tables, Tool Xtras' menu items, and so on.

Basically, for your Xtra's source code to be globalized, it needs to be savvy to the possibility that a string passed to it might be an MBCS string. Fortunately, to prepare for this, you don't need to do too much. Multi-byte text strings are still null-terminated, so ANSI functions like strlen() and so on won't blow up.

The biggest thing is to be careful if your code moves character by character through text strings. In 32-bit Windows, you should use the _mbsinc() and _mbsdec() calls to increment and decrement the proper number of bytes. In 16-bit Windows, the AnsiNext() and AnsiPrev() calls perform the same tasks. The Windows 32-bit Developer Kit has a whole set of multi-byte savvy string routines defined in "mbstring.h", but you shouldn't use these if you want you Xtras to work on 16-bit Windows as well. In actual practice, the normal ANSI routines seem to work just fine for all other string manipulations, provided you always increment/decrement your string pointers properly using the multi-byte savvy increment/decrement routines.

If your Xtra draws any text on Windows, you need to be careful not to use ANSI_CHARSET when you call CreateFont() to create the font you want to draw with. Ignore what the Windows API documentation says about this, because using ANSI_CHARSET will mangle many international symbol characters, and completely garble multi-byte text. Instead use DEFAULT_CHARSET (even though the Windows docs advise against it) and trust that Director is sending you the right character values to start with (it does).

The Macintosh Toolbox has been pretty savvy to multi-byte text strings for a long time. You can basically use multi-byte text strings in any Toolbox call the same way you use single byte strings, and the operating system is very smart about doing the right thing. The same caveats apply as on Windows when incrementing and decrementing your string pointers. The Metrowerks library routine mblen() measures the length of multibyte characters, so you can increment your strings using code like this:

#include "stdlib.h"

const char* nextchar (const char* str)
{
     // measures the char pointed to by str and increments str
     size_t len = mblen(str,2);
     return str + (len>1 ? 2 : 1);
}

const char* prevchar (const char* str)
{
     // measures the length of the char that's two bytes back
     // if it's two bytes long, returns str-2
     // otherwise it returns str-1
     
     size_t len = mblen(str-2,2);
     return str - (len>1 ? 2 : 1);
}
Note that European accents, symbols, etc. are NOT implemented as multi-byte characters (they're simply in the above-128 section of ASCII). This means that you can use the regular English language operating system and compilers to compile European-localized versions of an Xtra.

Localizing Xtras

Now, if you want a multi-byte localized Xtra, where all your menu items, text strings, etc., are in a language such as Japanese, the story changes, because you must make sure all your Xtra's own resources are multi-byte. This means that you must compile your Xtra on a multi-byte System. This little "gotcha" is true for both Macintosh and Windows platforms. On the Mac, you can get away with installing a "toolkit" like the Japanese Language Kit, but on Windows, you must be using a multi-byte versions of Windows, like Windows-J (Japanese). Fortunately, you can still use the English versions of CodeWarrior and Visual C++ to do your actual compiling, so you don't have to run out and buy Japanese or Arabic versions of your development tools. But unless the OS they are running on is multi-byte enabled, none of your resources will compile properly. (You do store all your Xtra's modifiable text strings in resources, right????)

Finally, Microsoft has an excellent section about software globalization/localization on their Web site, which is definitely worth a look if you want to create globalized Xtras.

Feedback

The information presented above is as accurate and up to date to the best of my knowledge. If you have any corrections, additions or comments about this article, please e-mail me any feedback and I will integrate the information into future versions.
©1994-2024 Electronic Ink. All rights reserved.
 
 
0