TweetFollow Us on Twitter

Sep 01 Mac OS X

Volume Number: 17 (2001)
Issue Number: 09
Column Tag: Mac OS X

Internationalizing Cocoa Applications - A Primer for Developers and End Localizers

by Andrew C. Stone

Now that you have written that amazing object-oriented Cocoa application, it’s time to bring the fruits of your creativity to the rest of the planet. This article has two components: the steps a developer needs to take to allow the application to be translated, and the steps the translator performs to localize an application to another language. What sets Cocoa localization apart from other development environment localization systems is its pure simplicity. Once an application has been prepared to be localizable by a developer, any number of languages can be added to the final product, without any recompiling by the developer or any access to the source by the parties who are doing the translations. In fact, the localizer can be a regular end user with a love of native language Mac OS X applications! These facts signify that you can ship your application in your native language, and then begin the process of internationalization afterwards. We’ll examine what the developer has to do, and then the steps required by the localizer.

Making An Application Localizable

Translatable text in a graphical user interface appears in two places: the Interface Builder files (nibs) which display menus and interfaces, and the embedded strings that are used in programmatically-created alert and dialog windows. A developer who follows a few guidelines will actually have no additional work to perform to localize their application:

  • Make all programmatic text, alert panel’s titles, messages and buttons use translation macros instead of quoted English strings
  • Always add interface files as localizable resources

Translatable Dictionaries - the .strings files

As you write your code, whenever you use a string that’s going to be displayed to the user, use one of the NSLocalizedString macros (NSLocalizedString, NSLocalizedStringFromTable, NSLocalizedStringFromTableInBundle). When your code is executed, these macros look up the string in a dictionary file with a “.strings” file ending. The .strings file is generated by a command line program, genstrings, that processes your code looking for the macros. Thus, there are three steps to creating the .strings files that get added to the English.lproj (we’ll use English as the native language in this article, although you can develop in any language using Project Builder):

  • Use the NSLocalizedString* macros in your code
  • Run genstrings to generate the .strings files
  • Add the generated files to your PB project as localizable resources

Here is a sample line of code, a message to set what the Undo menu displays once this action has been performed, which will appear in the user’s chosen language:

    [[self undoManager] setActionName:NSLocalizedStringFromTable(@”Change Print Info”, @”Muktinath”, 
    @”Action name for changing print info.”)];

NSLocalizedStringFromTable() takes the string to be displayed (“Change Print Info”), the table to look for the string in (Muktinath.strings), and a helpful comment for the person who is translating the phrase.

Running genstrings on this code would produce an entry in the Muktinath.strings table:\

/* Action name for changing print info. */
“Change Print Info” = “Change Print Info”;
The translator would then make a copy of the .strings file and translate the right hand side. For 
example, en Espaing i
/* Action name for changing print info. */
“Change Print Info” = “Cambiar Info de Imprimir”;

When using the macros in the standard alert panel, one technique to make your code easier to read is to use #defines, which also allows easy reuse:

#define TERMINATE_TITLE NSLocalizedStringFromTable(@”Quit”, @”PackIt”, “Title of alert panel”)

#define TERMINATE_MSG NSLocalizedStringFromTable(@”Remove temporary files?”, @”PackIt”, “Message when 
temp files exist”)

#define CANCEL NSLocalizedStringFromTable(@”Leave alone”, @”PackIt”, “Button title to not remove the 
files”) 

#define OK NSLocalizedStringFromTable(@”OK”,@”PackIt”, “Button choice for OK’ing a requested operation.”)
...
   if (NSRunAlertPanel(TERMINATE_TITLE,TERMINATE_MSG,OK,CANCEL,NULL) == NSAlertDefaultReturn) 
   ...

Generating the Strings files: genstrings

Once you have removed all direct uses of English strings in your program, then you are ready to collect all the translatable strings into their .strings files.

 Type “genstrings” in a terminal window to see its options:

Usage: genstrings [-j] [-s <routine-name>] [-o <output directory>] file1.[mc] ... 
filen.[mc]

Help: genstrings generates .strings file(s) from your source code.
      The names of your source files are the arguments: file1 ... filen.
      * C and Objective-C:
        Source lines with NSLocalizedString(string, comment) will
          generate an appropriate string table entry on Localizable.strings.
        Source lines with NSLocalizedStringFromTable(string, tablename, comment)
          will generate an appropriate string table entry in tablename.strings.
        Source lines with NSLocalizedStringFromTableInBundle(string, tablename, bundle, comment)
          will generate an appropriate string table entry in tablename.strings.
      * Java:
        The -j option sets the expected input language to Java.  In this case the above
          keywords are changed to Bundle.localizedString, Bundle.localizedStringFromTable,
          and Bundle.localizedStringFromTableInBundle (instead of the Objective-C defaults).
      The -s option substitutes its argument for NSLocalizedString.
        For example, -s MyLocalString will catch calls to MyLocalString
        and MyLocalStringFromTable.
      The -o option specifies what directory tables should be created in.

A simple invocation for a multi-level Objective C project would be something like:

genstrings *[hmc] */*[hmc] */*/*[hmc]

All source files in the top three levels would be searched to produce the output strings file. Add the produced .strings files to your resources folder in Groups & Files in Project Builder, and then make them localizable, as described in the next section.

Making Files Localizable

The developer’s second major job is to add all translatable Interface Builder files as “localizable”. In Project Builder:

  • 1. Add the new interface file (Project -> Add Files... or just drop it in to Groups & Files outline view - I like to place .nibs into “Resources”.

If you have saved the .nib file in English.lproj - then steps 2. and 3. are not necessary, otherwise:

  • 2. Project -> Info to bring up interface inspector
  • 3. Click “Localization & Platforms” popup - choose “Make Localized”


Adding other language versions of the interfaces is done with Project->Info with the file to localize selected.

This moves the interface file to the English.lproj in our example. To add a new language version, select the interface file in Groups & Files, choose “Add Localized Variant...” from the “Localization and Platforms” popup and type in the name of the language in English (example, for Espao the English.lproj in our example. To add a new language version, select the interface file in Groups & Files, choose “Add Localized Variant...” from the “Localization and Platforms” popup and type in the name of the languager of the user’s language preferences, if those languages exist in the project. The same procedure applies to .strings files and other resources that require localiization. The localizer now has the resources needed to translate the program.

End User Localization - Anyone can do this!

Localizing an application can be done by anyone who has a basic knowledge of Interface Builder, TextEdit, Terminal and how to open file packages in Finder. Interface Builder comes on the Developer CD that shipped with the original OS X 10.0, so you’ll need to install the Developer package if you haven’t already. A translator doesn’t even need to know how to use InterfaceBuilder if the developer extracts the localizable strings from the interfaces with a special tool, nibtool, described in the Advanced section below.

First, copy the application you wish to localize, just in case you mess something up! Since you will be editing files inside of the Application wrapper, you may to set the permissions so that you’ll be able to save the changes:

  1. Launch /Applications/Utilities/Terminal
  2. Change directory to where you copied the application cd <DIRECTORY>
  3. Change permissions to allow saving: chmod -R a+rwX <APPLICATION>.app

Now, you need to open the application wrapper. In Finder, hold down the control key while clicking on the application file and choose “Show Package Contents” from the contextual menu:


Control-Click an application to open it up

To test your application, set the system language to the one you are localizing. In System Preferences, International Pane, drag the language of choice to the top of the list:


Be sure to set your language before you launch our test application!!

An OS X application has one folder, “Contents”. Inside of that folder is “Resources”. In Resources, you’ll find English.lproj. This folder should be duplicated, and then renamed to the English version of your language, e.g. Spanish.lproj, Dutch.lproj, French.lproj, Japanese.lproj, German.lproj, Italian.lproj, etc.

Now you can edit all the files in your language’s .lproj directory and test your application by launching it anew!


There are three types of files to edit: .strings, .nib, and .html/.rtf informational/help files.

The .strings Files

The most boring task is to convert the strings which appear programmatically: the titles, messages, buttons from alert panels, and the “action names” that the Undo system uses to keep a track of what it’s undoing. (For example, if you change the way the page was layed out, the Edit menu would display “Undo Change Print Info”.) Sophisticated software like Stone Design’s Create® may have hundreds of operations that can be performed, and require translation. Smaller applications may have very few of these, so don’t get discouraged!

These strings appear in .strings files in the .lproj directories. You can use the free, Apple-provided, and Cocoa-based TextEdit program to edit these files; TextEdit supports unicode, the lingua franca of the Cocoa Text system, so all of the special characters found in other languages will be correctly preserved. Because the .strings extension is not registered with TextEdit, double-clicking a .strings file brings up the ‘There is no application available to open the document “Something.strings”- “Choose Application”’ dialog. To avoid this, place TextEdit in your dock, and drag the .strings file on top of the TextEdit icon to quickly open the file.

On the left hand side of a typical entry in the .strings file, the development language string appears, in quotes, followed by an equals sign. The right hand side of the entry is to be replaced by the equivalent phrase in your language. Finally, because these files need to be easily parsed by the application, the entry ends in a semi-colon, and uses /* and */ to delimit comments:

/* Name of Resource Source - like Patterns */
“Pattern” = “Pattern”;

So, the French localizer would translate the second half into:

“Pattern” = “Texture”;

And the Spanish localizer:

“Pattern” = “Motivo”;

And the German localizer:

“Pattern” = “Muster”;

One note about translating strings is the occurrence of format strings within the quotes. The programmer can use %@, %d, %f and other “sprintf”-style placeholders to place runtime information in the programmatically-generated text. For example, the following string will display the name of the pattern:

/* alert message to prevent removal of default pattern */
“You cannot delete the %@ pattern.” = “You cannot delete the %@ pattern.”;

When the program is running, the message would replace the %@ with the actual name of the pattern that cannot be deleted.

The localizer must take care to preserve the number and order of these placeholders. Programmers should make this easier for translators by providing info on the parameters in the comments. In the case of multiple parameters, the parameters are passed in order, and localizers need to keep this mind, even if it means awkward sentence structure, because otherwise, the program will crash! Be careful.

To insert quotes into the quoted string prefix the quote with a backslash: “The word \”quotes\” is quoted.” To insert a single, literal “%” in a string, use “%%”.

Besides the genstrings-produced .strings files, there is also an InfoPlist.strings file which has a few strings that can be localized:

{
    CFBundleGetInfoString = “Stone Design’s Create®. © 1990-2001, Stone Design Corp. 
    Visit www.stone.com”;
    NSHumanReadableCopyright = “© 1990-2001, Stone Design Corp.\nVisit www.stone.com”;
    // Document type human-readable names.
    “Stone Design Graphic Format” = “Stone Create (cre8)”;
    “NSPDFPboardType” = “Portable Document Format (PDF)”;
    “NSTIFFPboardType” = “Tagged Image File Format (TIFF)”;
    CFBundleHelpBookName = “Create Online Manual”;
    CFAppleHelpAnchor = "CreateHelp";
}

By translating the file types such as "NSPDFPboardType", you can have more attractive popups in your Save panels. The CFBundleHelpBookName key controls the display title of the Apple Viewer help your application provides and should be translated.

The Interfaces - Using Interface Builder

Now comes the fun part! Interface Builder lets you open and edit the .nib (NeXT Interface Builder) files, which are the actual interfaces used by a program. To give yourself a real boost, first translate the nib that contains the main menu, usually named the same as the application, e.g. "GIFfun.nib":

The process of converting the IB files goes like this:

for each IB file do:

  • For each string you see, double-click it to edit, and replace with a translated word or phrase
  • If necessary resize the control according to the feedback provided by IB
  • If an interface element has a help tip, translate that as well
    Save and test by quitting and relaunching the application

A few fine points:

  • You can tab between menu and matrix items to increase editing speed
  • To set the title of a window, click on the window, select Tools->Show Info, and select "Attributes" in the popup
  • Note that IB (and OS X) requires that you hit <RETURN> or <TAB> to make your edits "stick".
  • Don’t forget to translate each pane in a TabView: Double-click each tab to make its pane visible

Each interface element can have an attached Help Tip - those cute little yellow windows that pop up if you leave your mouse over a control for a few seconds that describe the functionality of the control. To change these:

  • Select the control
  • Tools->Show Info, "Help" popup pane
  • Enter the tip in your language, and be sure to hit <RETURN> to make it stick

Advanced Localization Topics: Bundles, nibtool and Apple Viewer Help

As usual, the simple life ain’t so simple! One thing to watch for is good engineering on the part of the developer. Cocoa is a dynamic, runtime bound system, which means that objects (code and interfaces) can be loaded upon demand, not when the program starts. In Create®, for example, there are 50 interfaces which are dynamically loaded. This means very fast launch times, and much better memory usage, because you only load resources that you use as you use them. These "bundles" are layed out in a similar manner to the packaging of the application; each .bundle folder contains a Contents folder, which has the Resources folder, which contains an English.lproj with all localizable resources for that bundle. Most bundles just have one nib file — but you need to repeat the process described above (duplicate the English.lproj, rename it to your language in English, and localize the files in the .lproj) for each .bundle folder in the application’s Resources folder.

With the introduction of InterfaceBuilder 2.1, Apple has provided localization capabilities to the command line utility named nibtool (/usr/bin/nibtool). nibtool can extract the localizable strings in a nib to a .strings file, which can be translated, and then reincorporated into a copy of the nib file. This will not adjust spacing of the UI elements so it’s just a start, but it might help things go faster.

To generate the strings file for a particular nib file:

nibtool -L myfile.nib > file.strings

file.strings will now contain entries such as "key" = "key" and be in Unicode (UTF-16) format. Next, give the resulting .strings file to a translator and have them convert the second "key" entry to "key in other language"

To reincorporate these translated strings:

nibtool -d file.strings -w newLocalization.nib myfile.nib

nibtool will take the contents of file.strings and replace "key" in myfile.nib with "something in other language" in the translated version "newLocalization.nib".

The final, and most demanding, part of the translation is the Online Help system - the folder of linked .html files that contains a special "Sherlock-style" index for instant searching. Stone Design keeps our help files in Create®, the localizer then edits the help directly, and produces the HTML with a simple export. This is usually easier than hand-hacking html because you also want to change the screenshots to reflect the translated interfaces. Please read my MacTech article of a few months ago entitled "Help On The Way! A guide for the perplexed on adding Apple Help to your OS X application" for complete instructions on adding online help to an application.

Conclusion

OS X has complete support for internationalization and is simple enough that end users can add new languages. With a small amount of effort, developers can produce applications which can be translated to new languages out in the field, without access to source code, by regular yet adventurous users.


Andrew Stone andrew@stone.com is founder of Stone Design Corp http://www.stone.com/ and divides his time between farming on the earth and in cyperspace.

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Apple High Sierra 10.13 - The latest OS...
macOS High Sierra introduces new core technologies that improve the most important functions of your Mac. From rearchitecting how it stores your data to improving the efficiency of video streaming to... Read more
ScreenFlow 7.1 - Create screen recording...
ScreenFlow is powerful, easy-to-use screencasting software for the Mac. With ScreenFlow you can record the contents of your entire monitor while also capturing your video camera, microphone and your... Read more
Airmail 3.5 - Powerful, minimal email cl...
Airmail is an mail client with fast performance and intuitive interaction. Support for iCloud, MS Exchange, Gmail, Google Apps, IMAP, POP3, Yahoo!, AOL, Outlook.com, Live.com. Airmail was designed... Read more
CleanMyMac 3.9.0 - $39.95
CleanMyMac makes space for the things you love. Sporting a range of ingenious new features, CleanMyMac lets you safely and intelligently scan and clean your entire system, delete large, unused files... Read more
Numi 3.17.2 - Menu-bar calculator suppor...
Numi is a calculator that magically combines calculations with text, and allows you to freely share your computations. Numi combines text editor and calculator Support plain English. For example, '5... Read more
OmniGraffle 7.4.3 - Create diagrams, flo...
OmniGraffle helps you draw beautiful diagrams, family trees, flow charts, org charts, layouts, and (mathematically speaking) any other directed or non-directed graphs. We've had people use Graffle to... Read more
ExpanDrive 6.1.0 - Access cloud storage...
ExpanDrive builds cloud storage in every application, acts just like a USB drive plugged into your Mac. With ExpanDrive, you can securely access any remote file server directly from the Finder or... Read more
VueScan 9.5.86 - Scanner software with a...
VueScan is a scanning program that works with most high-quality flatbed and film scanners to produce scans that have excellent color fidelity and color balance. VueScan is easy to use, and has... Read more
Cocktail 11.0 - General maintenance and...
Cocktail is a general purpose utility for macOS that lets you clean, repair and optimize your Mac. It is a powerful digital toolset that helps hundreds of thousands of Mac users around the world get... Read more
OmniGraffle Pro 7.4.3 - Create diagrams,...
OmniGraffle Pro helps you draw beautiful diagrams, family trees, flow charts, org charts, layouts, and (mathematically speaking) any other directed or non-directed graphs. We've had people use... Read more

Morphite guide - how to explore like a p...
The much anticipated space exploration game, Morphite, has finally arrived, and we can't get enough of it. The game is essentially everything we wanted No Man's Sky to be. It's a game that puts a heavy focus on exploring foreign worlds, but the... | Read more »
The best visual novels on mobile
Narrative games have been around for ages, but only now have they been creeping into the mainstream spotlight. These games tell some of the industry's finest stories, and they break new ground in terms of gameplay and mechanics regularly. Here are... | Read more »
The best new games we played this week -...
It's pretty much been one big release after another. We were privy to a bunch of surprises this week, with a lot of games we'd been waiting for quite some time dropping unexpectedly. We hope you're free this weekend, because there is a lot for... | Read more »
Stormbound: Kingdom Wars guide - how to...
Stormbound: Kingdom Wars is an excellent new RTS turned card battler out now on iOS and Android. Lovers of strategy will get a lot of enjoyment out of Stormbound's chess-like mechanics, and it's cardbased units are perfect for anyone who loves the... | Read more »
The best AR apps and games on iOS right...
iOS 11 has officially launched, and with it comes Apple's ARKit, a helpful framework that makes it easier than ever for developers to create mobile AR experiences. To celebrate the occassion, we're featuring some of the best AR apps and games on... | Read more »
Phoenix Wright: Ace Attorney - Spirit of...
Phoenix Wright: Ace Attorney - Spirit of Justice 1.00.00 Device: iOS Universal Category: Games Price: $.99, Version: 1.00.00 (iTunes) Description: ************************************************※IMPORTANT※・Please read the “When... | Read more »
Kpressor (Utilities)
Kpressor 1.0.0 Device: iOS Universal Category: Utilities Price: $4.99, Version: 1.0.0 (iTunes) Description: The ultimate ZIP compression application for iPhone and iPad. - Full integration of iOS 11 with support for multitasking.-... | Read more »
Find out how you can save £35 and win a...
Nothing raises excitement like a good competition, and we’re thrilled to announce our latest contest. We’ll be sending one lucky reader and a friend to the Summoners War World Arena Championship at Le Comedia in Paris on October 7th. It’s the... | Read more »
Another Lost Phone: Laura's Story...
Another Lost Phone: Laura's Story 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: Another Lost Phone is a game about exploring the social life of a young woman whose phone you have just... | Read more »
The Witness (Games)
The Witness 1.0 Device: iOS Universal Category: Games Price: $9.99, Version: 1.0 (iTunes) Description: You wake up, alone, on a strange island full of puzzles that will challenge and surprise you. You don't remember who you are, and... | Read more »

Price Scanner via MacPrices.net

Snag a Certified Refurbished Apple Pencil for...
Apple has Certified Refurbished Apple Pencils available for $85 including free shipping. Their price is $14 off MSRP, and it’s the lowest price available for a Pencil. Read more
12-inch 64GB iPad Pro on sale for $749, save...
Adorama has 12″ 64GB iPad Pros on sale today for $749 including free shipping plus NY & NJ sales tax only. Their price is $50 off MSRP. Read more
Apple Certified Refurbished iPad minis availa...
Apple has Certified Refurbished 128GB iPad minis available today for $339 including free shipping. Apple’s standard one-year warranty is included. Their price is $60 off MSRP. Read more
12-inch 1.2GHz Retina MacBook Pros on sale fo...
B&H Photo has 2017 12″ 1.2GHz Retina MacBooks on sale for $100 off MSRP. Shipping is free, and B&H charges sales tax in NY & NJ only: 12″ 1.2GHz Space Gray MacBook: $1199 $100 off MSRP 12... Read more
Sunday sale: 13-inch 3.1GHz MacBook Pros for...
Amazon has 2017 13″ 3.1GHz MacBook Pros on sale today for up to $150 off MSRP, each including free shipping: – 13″ 3.1GHz/256GB Space Gray MacBook Pro (MPXV2LL/A): $1649.99 $150 off MSRP – 13″ 3.1GHz... Read more
Looking for a 2017 12″ Retina MacBook? Save $...
Apple has Certified Refurbished 2017 12″ Retina MacBooks available for $200-$240 off the cost of new models. Apple will include a standard one-year warranty with each MacBook, and shipping is free.... Read more
Apple Offering Up To $455 Credit Toward iPhon...
iPhone 8 and 8 Plus are now available at the Apple Store, and you can receive up to $375 credit toward a new iPhone purchase when you trade in your eligible smartphone. Photo Courtesy Apple Just... Read more
AnyTrans Offers iOS Users Three Ways For Movi...
iMobie Inc. today announceed AnyTrans v6.0.1, which now can help iOS users move all data to iPhone 8/8 Plus seamlessly. The software is available both on Mac and Windows and fully able to move all... Read more
Snag a 13-inch 2.3GHz MacBook Pro for $100 of...
B&H Photo has 2017 13″ 2.3GHz MacBook Pros in stock today and on sale for $100 off MSRP, each including free shipping plus NY & NJ sales tax only: – 13-inch 2.3GHz/128GB Space Gray MacBook... Read more
Verizon offers new iPhone 8 for $100-$300 off...
Verizon is offering the new iPhone 8 for up to $300 off MSRP with an eligible trade-in: • $300 off: iPhone 6S/6S Plus/7/7 Plus, Google Pixel XL, LG G6, Moto Z2 Force, Samsung Galaxy S7/S7 edge/S8/S8... Read more

Jobs Board

Development Operations and Site Reliability E...
Development Operations and Site Reliability Engineer, Apple Payment Gateway Job Number: 57572631 Santa Clara Valley, California, United States Posted: Jul. 27, 2017 Read more
Data Engineer - *Apple* Media Products - Ap...
Job Summary Apple is seeking a highly skilled data engineer to join the Data Engineering team within Apple Media Products. AMP (home to Apple Music, App Read more
Development Operations and Site Reliability E...
Development Operations and Site Reliability Engineer, Apple Payment Gateway Job Number: 57572631 Santa Clara Valley, California, United States Posted: Jul. 27, 2017 Read more
Development Operations and Site Reliability E...
Development Operations and Site Reliability Engineer, Apple Payment Gateway Job Number: 57572631 Santa Clara Valley, California, United States Posted: Jul. 27, 2017 Read more
*Apple* Retail - Multiple Positions - Apple,...
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.