TweetFollow Us on Twitter

Dynamic Localization
Volume Number:11
Issue Number:3
Column Tag:Think Globally, Act Locally

Dynamic Localization

Prepare your software for going global

By Brian Sutter, MindVision Software

Note: Source code files accompanying article are located on MacTech CD-ROM or source code disks.

Recently, while working on our installer program, one of our developers needed a feature to dynamically localize the installer to the language in use on the destination computer. That is, when the installer runs, make sure it uses the language that the user expects to see. After throwing around ideas for a couple of days, we agreed on a way to do it (sometimes you just have to let the boss win the arguments just so you don’t ruin your chance of getting a pay raise).

Breaking Things Down

While thinking about how to do dynamic localization, it occurred to us there are two groups of resources that our application needs to use. One group of resources don’t need to be localized. For example, CODE, ICN#, CURS, LDEF, etc. These are the resources users will never see, or are the same in every language. The other group of resources need to be localized for different languages. For example, STR#, DITL, STR , vers, etc These are resources the user may read at one time or another.

Now, when we build an installation kit, we typically put everything into a single file which we call an installer. A good part of the challenge we faced was how to keep everything in a single file while still allowing ourselves to keep all the localizing material in resources like everyone is used to. In this article, I’ll go through the specifics of how we dealt with this challenge in our application, and provide code samples you might find useful for doing similar things.

We broke our installer down into two parts. The first part we call the “Base Installer”, which includes the resources that don’t need to be localized. The second part includes resources that need to be localized for each language the installer needs to support. For example, we need different DITL and STR# resources for each different language we want to support. For these resources we have files called, “English Installer” , “French Installer”, “German Installer”, etc. We call these our “Language Resource Files”.

We have all these different files of resources, and we want to combine them all into a single file (so users see only one file, not a bunch of files). For example, we have STR# with ID of 1000 for English, French, German, Italian, etc. How can our installer have resources with these same types and IDs in it? The answer is, don’t. When we assemble our application, we open each language resource file for block reading, and read the entire resource fork into a handle. We write the handle into our own resource type of ‘Lirs’, and give it an ID based on the language. Here’s how we did it.

OSErr ResFile2Resource(Str32 *fileName, short vRefNum, 
      long dirID, short languageID);
{
 OSErr  err;
 short  refNum;
 long     eof;
 Handle   tHandle;

    // Open the resource fork of the file for BLOCK reads
 if (err = HOpenRF(vRefNum,dirID,fileName,fsRdPerm,&refNum)) goto exit:

    // Get the size of the resource fork
 if (err = GetEOF(refNum, &eof)) goto exitErr;

    // Create a handle to hold the entire resource fork
 tHandle = NewHandle(eof);
 if (err = MemError()) goto exitErr;

    // Read the entire resource fork into our handle
 if (err = FSRead(refNum, &eof, *tHandle)) goto exitErr;
 
    // The current resource file is our installer application
    // Add this entire resource fork to our installer application
 AddResource(tHandle,'Lirs',languageID,"\p");
 if (err = ResError()) goto exitErr;

 WriteResource(tHandle);
 err = ResError();

    // Release memory occupied by this resource
 ReleaseResource(tHandle);
 tHandle = nil;

exitErr:
 FSClose(refNum);
 if (tHandle) DisposeHandle(tHandle);

exit:
 return err;
}

We call ResFile2Resource for every file containing localized resources.

• filename is the name of the resource file on hard drive.

• vRefNum is the volume reference number where the file resides.

• dirID is the directory id on the specified volume where the file resides.

• languageID is the resource ID of the language file. We use the same defines as Apple’s Languages.h file for the resource IDs for different languages, but we add 1000 to those numbers because Apple says don’t use resource ID’s less than 128. So for the English resources the ID = 1000, French = 1001, German = 1002, etc.

Once we’ve called ResFile2Resource for each file of localized resources, each is a resource in our installer application.

We’ve got an additional twist for our application. An installer may need to create a number of files. Each of these files may need a localized name. The next thing we do is add lists of localized file names (supplied by the developer) to be installed, one for each language. We use the same ID scheme as the above language resources, but use the ‘Flnm’ (filename) resource type. The developer stores these in another resource file. When the installer is built, we merge these ‘Flnm’ resources into the installer application.

After these language and filename resources are added to the installer, we add the rest of the stuff our application needs to carry around (all the stuff that’s going to get installed).

Language Magic

When our application is launched, we do a little magic to find out what language is being used on the user’s Mac.

// Assume English in case something fails
gLanguageCode  = 0;

// The following chunk of code was graciously provided to me by a engineer at 
// Adobe Systems, THANKS!
// Make sure Script Manager calls are available
if (TrapAvailable(_ScriptUtil)) {

    // Get the ID of the current system font and use it to find out
    // the script code
 scriptCode = Font2Script(GetSysFont());

    // use the script code to find out the language code for that script
   gLanguageCode = GetScript(scriptCode,smScriptLang);
 
    // “GetScript(scriptCode, smScriptLang)” doesn’t return the
    // correct language code on KanjiTalk 6.0.7-J, if it returns zero and if
    // the current script is not Roman, we directly get the language code
    // from the itlb resource.
 if (gLanguageCode == 0 && scriptCode != 0) {                  
 if (tHandle = GetResource('itlb', scriptCode)) {
 gLanguageCode = (*(ItlbRecord **)tHandle)->itlbLang;
 }
 }

}

// Add 1000 to get the resource ID of localized resources
gLanguageCode += 1000;

At this point in the process, the current resource file is our installer application, and it contains all the localized resources and filenames the installer needs to localize itself for the current language.

Localizing File Names

Now that we know which language resource ID to search for (gLanguageCode), we’ll call Get1Resource to find any localized filenames to install. If it’s found, we copy the localized names to the list of file names to install. If not, we’ll just leave the file names alone.

// See if there are any localized filenames
tFilesHdl = Get1Resource('Flnm', gLanguageCode);
if (tFilesHdl) {
    .. Our installer contains a handle of filenames, so we need to call a routine to                      
    .. replace the original names with these localized filenames.
 ReleaseResource(tFIlesHdl);
}

Localizing Installer Resources

Now that we have localized file names, let’s see if there are localized resources for the installer. Remember that these resources contain entire resource forks of the localized language files.

// See if there are any localized resources.
tHandle = Get1Resource('Lirs',gLanuageCode);
if (tHandle) {
 DetachResource(tHandle);

    // Store the size of the resource
 count = GetHandleSize(tHandle);

    // Call routine to find a volume that is large enough to create a file the            
    // size of the resource.
 vRefNum = FindValidVolume(count);

 if  (vRefNum) {
    // Come up with a unique filename
 NumToString(TickCount(),tFileName);

    // Create file to the root directory (dirID = 2)
 err = HCreateResFile(vRefNum, 2, tFileName);
 if (err) goto doDispose;

    // Open the Resource fork for block writing
 err = HOpenRF(vRefNum, 2, tFileName, &refNum);
 if (err) goto doDispose;

    // Write out resource to create the file’s resource fork
 err = FSWrite(refNum, &count,*tHandle);

 FSClose(refNum);
 if (err) goto doDispose;

    // Open the resource file we just created
 gExtraResRefNum = HOpenResFile(vRefNum, 2, tFileName, 
 fsRdPerm);
 }

doDispose:
 DisposeHandle(tHandle);
}

If we successfully create and open this resource file, it will be the current resource file, and it will be searched first for dialogs, strings, and other resources. If the Resource Manager isn’t able to find it there, it will automatically search in the installer application’s resources to find what it needs.

One thing not discussed here is how to make the temporary resource file invisible. It’s a good thing to do so the user won’t see a weird file name appear on their volume while the install is taking place.

resNotFound (0xFF40)

What happens when the language in use on the destination computer isn’t supported by the installer? The installer could bring up a dialog alerting the user to this fact, and allow them to choose the language to install, but what language do you use for this dialog? We chose to sidestep the problem by running with a default language if the system language is not supported by the installer.

Clean Up After Yourself

Before quitting our application, we need to clean up a little bit. We need to close and delete the file of localized resources.

// Cleanup
if (gExtraResRefNum != -1) {
    // Since we don’t store this filename anywhere, we call PBGetFCBInfo to get it
 FCBPBRec pb;
 OSErr  err;
 Str32  tStr;
 
 pb.ioFCBIndx = 0; // We’re not indexing
 pb.ioVRefNum = 0; // 0 = All open files
 pb.ioRefNum = gExtraResRefNum;  // Refnum of our resource file
 pb.ioNamePtr = tStr;// Storage place for the name
 err = PBGetFCBInfo(&pb, false);
 if (!err) {
    // Close the Resource File before trying to delete it
 CloseResFile(gExtraResRefNum);

    // Delete the Resource File now that we have the vRefNum, directory ID,
    // and the Filename
 err = HDelete(pb.ioFCBVRefNum, pb.ioFCBParID, tStr);
 }
}

Other Localization Tips

Other localization items to keep in mind when writing your application:

• Double byte languages. Make sure any strings you allocate in your applications are long enough to support double byte languages.

• Make sure all strings are in resources. Don’t hard code any text within your application. This will save you from having to recompile multiple versions of your application, one for each language. It’s a lot easier to add different resources to one set of compiled code than it is to maintain multiple sources.

• Don’t split your strings up and recombine them later. You might be surprised by what happens when different language grammar rules are applied.

• Really, don’t embed any strings, not even single character strings like quotes. Some languages use multiple characters for quotation, so patching the application gets terribly unpleasant.

• Don’t specify a font by name when you really mean system font or application font.

Tipping is Not a City in China

Another tip for copying the resource fork of a file: use block read and write operations, don’t use the resource manager. You might be surprised how many programs copy or build applications by copying a resource at a time. This is way too slow! Even if you don’t need all of the resources, in most cases it’s better to copy the entire resource fork using block reads and writes and then delete the resources which aren’t needed.

// Copying the Resource Fork from one file to another 
HOpenRF(sourceFile &sourceRefNum);
HOpenRF(destFile &destRefNum);
GetEOF(sourceRefNum,&sourceSize);
CopyBytes(sourceRefNum,destRefNum,sourceSize);
FSClose(sourceRefNum);
FSClose(destRefNum);

// If you need to, then delete some resources 
SetResLoad(false);
destRefNum = HOpenResFile(destFile );
Get1Resource();
RmveResource();
CloseResFile(destRefNum);
SetResLoad(true);

Notice the SetResLoad(false). You don’t have to load in an entire resource to be able to delete it. Also, call SetResLoad(false) before opening the resource file to prevent “preload” resources from loading. It saves time and space. Just be sure to set it back to true when you’re done.

File This Tip Away

For examples on how to do just about any file operation, look for “MoreFiles” on the Developer CDs from Apple [one random place on the Internet that we found it was at:

ftp://src.doc.ic.ac.uk/computing/systems/mac/Mac-Technical/sc/morefiles,

and there’s always Apple’s site:

ftp://ftp.info.apple.com/Apple.Support.Area/Developer_Services - ed stb].

Picture If You Will

Now it’s time to give you a visual example of the difference you might see. Here’s an example of an installer as presented in English.

English System

Here’s the installer localized to German and Kanji. I don’t speak German or Japanese, so I wasn’t able to localize the “Install your favorite ” text in the window. I just changed the text to show you that it does show different text for German and Kanji systems.

German System

Kanji System

Here’s a screen dump of our app in ResEdit. It contains all the normal resources as well as our two special resources:

‘Flnm’ - Resource containing the localized file names for German and Kanji.

‘Lirs’ - Resource containing the localized resources for the dialogs, strings, etc. for German and Kanji.

There is also a TEXT resource containing the text to appear in the installer window - one for each language (English, German, and Kanji.)

Notice there isn’t a separate English resource for ‘Flmn’ and ‘Lirs’. This is because English is the default language and those resources are represented by the normal DLOG, STR#, MENU resources in the Segment.1 file.

Well, now you’ve seen how we go about adapting to the current situation. I hope this gives you some ideas about how you might pack more punch into your software.

 
AAPL
$104.80
Apple Inc.
-0.04
MSFT
$45.99
Microsoft Corpora
+0.97
GOOG
$538.12
Google Inc.
-5.86

MacTech Search:
Community Search:

Software Updates via MacUpdate

OS X Server 4.0 - For OS X 10.10 Yosemit...
Designed for OS X and iOS devices, OS X Server makes it easy to share files, schedule meetings, synchronize contacts, develop software, host your own website, publish wikis, configure Mac, iPhone,... Read more
TotalFinder 1.6.12 - Adds tabs, hotkeys,...
TotalFinder is a universally acclaimed navigational companion for your Mac. Enhance your Mac's Finder with features so smart and convenient, you won't believe you ever lived without them. Tab-based... Read more
BusyCal 2.6.3 - Powerful calendar app wi...
BusyCal is an award-winning desktop calendar that combines personal productivity features for individuals with powerful calendar sharing capabilities for families and workgroups. BusyCal's unique... Read more
calibre 2.7 - Complete e-library managem...
Calibre is a complete e-book library manager. Organize your collection, convert your books to multiple formats, and sync with all of your devices. Let Calibre be your multi-tasking digital... Read more
Skitch 2.7.3 - Take screenshots, annotat...
With Skitch, taking, annotating, and sharing screenshots or images is as fun as it is simple.Communicate and collaborate with images using Skitch and its intuitive, engaging drawing and annotating... Read more
Delicious Library 3.3.2 - Import, browse...
Delicious Library allows you to import, browse, and share all your books, movies, music, and video games with Delicious Library. Run your very own library from your home or office using our... Read more
Art Text 2.4.8 - Create high quality hea...
Art Text is an OS X application for creating high quality textual graphics, headings, logos, icons, Web site elements, and buttons. Thanks to multi-layer support, creating complex graphics is no... Read more
Live Interior 3D Pro 2.9.6 - Powerful an...
Live Interior 3D Pro is a powerful yet very intuitive interior designing application. View Video Tutorials It has every feature of Live Interior 3D Standard, plus some exclusive ones: Create multi... Read more
The Hit List 1.1.7 - Advanced reminder a...
The Hit List manages the daily chaos of your modern life. It's easy to learn - it's as easy as making lists. And it's powerful enough to let you plan, then forget, then act when the time is right.... Read more
jAlbum Pro 12.2.4 - Organize your digita...
jAlbum Pro has all the features you love in jAlbum, but comes with a commercial license. With jAlbum, you can create gorgeous custom photo galleries for the Web without writing a line of code!... Read more

Latest Forum Discussions

See All

Rami Ismail Opens Up distribute​() for D...
Rami Ismail Opens Up distribute​() for Developers Posted by Jessica Fisher on October 24th, 2014 [ permalink ] Rami Ismail, Chief Executive of Business and Development at indie game studio | Read more »
Great Hitman GO Goes on Sale and Gets Ne...
Great Hitman GO Goes on Sale and Gets New Update – Say That Three Times Fast Posted by Jessica Fisher on October 24th, 2014 [ permalink ] | Read more »
Rival Stars Basketball Review
Rival Stars Basketball Review By Jennifer Allen on October 24th, 2014 Our Rating: :: RESTRICTIVE BUT FUNUniversal App - Designed for iPhone and iPad Rival Stars Basketball is a fun mixture of basketball and card collecting but its... | Read more »
Rubicon Development Makes Over a Dozen o...
Rubicon Development Makes Over a Dozen of Their Games Free For This Weekend Only Posted by Jessica Fisher on October 24th, 2014 [ permalink ] | Read more »
I Am Dolphin Review
I Am Dolphin Review By Jennifer Allen on October 24th, 2014 Our Rating: :: NEARLY FIN-TASTICUniversal App - Designed for iPhone and iPad Swim around and eat nearly everything that moves in I Am Dolphin, a fun Ecco-ish kind of game... | Read more »
nPlayer looks to be the ultimate choice...
Developed by Newin Inc, nPlayer may seem like your standard video player – but is aiming to be the best in its field by providing high quality video play performance and support for a huge number of video formats and codecs. User reviews include... | Read more »
Fighting Fantasy: Caverns of the Snow Wi...
Fighting Fantasy: Caverns of the Snow Witch Review By Jennifer Allen on October 24th, 2014 Our Rating: :: CLASSY STORYTELLINGUniversal App - Designed for iPhone and iPad Fighting Fantasy: Caverns of the Snow Witch is a sterling... | Read more »
A Few Days Left (Games)
A Few Days Left 1.01 Device: iOS Universal Category: Games Price: $3.99, Version: 1.01 (iTunes) Description: Screenshots are in compliance to App Store's 4+ age rating! Please see App Preview for real game play! **Important: Make... | Read more »
Toca Boo (Education)
Toca Boo 1.0.2 Device: iOS Universal Category: Education Price: $2.99, Version: 1.0.2 (iTunes) Description: BOO! Did I scare you!? My name is Bonnie and my family loves to spook! Do you want to scare them back? Follow me and I'll... | Read more »
Intuon (Games)
Intuon 1.1 Device: iOS Universal Category: Games Price: $.99, Version: 1.1 (iTunes) Description: Join the battle with your intuition in a new hardcore game Intuon! How well do you trust your intuition? Can you find a needle in a... | Read more »

Price Scanner via MacPrices.net

Nimbus Note Cross=Platform Notes Utility
Nimbus Note will make sure you never forget or lose your valuable data again. Create and edit notes, save web pages, screenshots and any other type of data – and share it all with your friends and... Read more
NewerTech’s Snuglet Makes MagSafe 2 Power Con...
NewerTech has introduced the Snuglet, a precision-manufactured ring designed to sit inside your MagSafe 2 connector port, providing a more snug fit to prevent your power cable from unintentional... Read more
Apple Planning To Sacrifice Gross Margins To...
Digitimes Research’s Jim Hsiao says its analysts believe Apple is planning to sacrifice its gross margins to save its tablet business, which has recently fallen into decline. They project that Apple’... Read more
Who’s On Now? – First Instant-Connect Search...
It’s nighttime and your car has broken down on the side of the highway. You need a tow truck right away, so you open an app on your iPhone, search for the closest tow truck and send an instant... Read more
13-inch 2.5GHz MacBook Pro on sale for $949,...
Best Buy has the 13″ 2.5GHz MacBook Pro available for $949.99 on their online store. Choose free shipping or free instant local store pickup (if available). Their price is $150 off MSRP. Price is... Read more
Save up to $125 on Retina MacBook Pros
B&H Photo has the new 2014 13″ and 15″ Retina MacBook Pros on sale for up to $125 off MSRP. Shipping is free, and B&H charges NY sales tax only. They’ll also include free copies of Parallels... Read more
Apple refurbished Time Capsules available sta...
The Apple Store has certified refurbished Time Capsules available for up to $60 off MSRP. Apple’s one-year warranty is included with each Time Capsule, and shipping is free: - 2TB Time Capsule: $255... Read more
Textilus New Word, Notes and PDF Processor fo...
Textilus is new word-crunching, notes, and PDF processor designed exclusively for the iPad. I haven’t had time to thoroughly check it out yet, but it looks great and early reviews are positive.... Read more
WD My Passport Pro Bus-Powered Thunderbolt RA...
WD’s My Passport Pro RAID solution is powered by an integrated Thunderbolt cable for true portability and speeds as high as 233 MB/s. HighlightsOverviewSpecifications Transfer, Back Up And Edit In... Read more
Save with Best Buy’s College Student Deals
Take an additional $50 off all MacBooks and iMacs at Best Buy Online with their College Students Deals Savings, valid through November 1st. Anyone with a valid .EDU email address can take advantage... Read more

Jobs Board

*Apple* Solutions Consultant - Apple Inc. (U...
…important role that the ASC serves is that of providing an excellent Apple Customer Experience. Responsibilities include: * Promoting Apple products and solutions Read more
Senior Event Manager, *Apple* Retail Market...
…This senior level position is responsible for leading and imagining the Apple Retail Team's global event strategy. Delivering an overarching brand story; in-store, Read more
*Apple* Solutions Consultant (ASC) - Apple (...
**Job Summary** The ASC is an Apple employee who serves as an Apple brand ambassador and influencer in a Reseller's store. The ASC's role is to grow Apple Read more
Project Manager / Business Analyst, WW *Appl...
…a senior project manager / business analyst to work within our Worldwide Apple Fulfillment Operations and the Business Process Re-engineering team. This role will work Read more
*Apple* Retail - Multiple Positions (US) - A...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.