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 Security Update 2015-005 - For OS...
Apple Security Update 2015-005 is recommended for all users and improves the security of OS X. For detailed information about the security content of this update, please visit: http://support.apple.... Read more
Apple HP Printer Drivers 3.1 - For OS X...
Apple HP Printer Drivers includes the latest HP printing and scanning software for OS X Lion or later. For information about supported printer models, see this page. Version 3.1: The latest printing... Read more
Epson Printer Drivers 3.1 - For OS X 10....
Epson Printer Drivers installs the latest software for your EPSON printer or scanner for OS X Yosemite, OS X Mavericks, OS X Mountain Lion, and OS X Lion. For more information about printing and... Read more
Xcode 6.4 - Integrated development envir...
Xcode provides everything developers need to create great applications for Mac, iPhone, and iPad. Xcode brings user interface design, coding, testing, and debugging into a united workflow. The Xcode... Read more
OS X Yosemite 10.10.4 - Apple's lat...
OS X Yosemite is Apple's newest operating system for Mac. An elegant design that feels entirely fresh, yet inherently familiar. The apps you use every day, enhanced with new features. And a... Read more
Dash 3.0.2 - Instant search and offline...
Dash is an API Documentation Browser and Code Snippet Manager. Dash helps you store snippets of code, as well as instantly search and browse documentation for almost any API you might use (for a full... Read more
FontExplorer X Pro 5.0 - Font management...
FontExplorer X Pro is optimized for professional use; it's the solution that gives you the power you need to manage all your fonts. Now you can more easily manage, activate and organize your... Read more
Typinator 6.6 - Speedy and reliable text...
Typinator turbo-charges your typing productivity. Type a little. Typinator does the rest. We've all faced projects that require repetitive typing tasks. With Typinator, you can store commonly used... Read more
Arq 4.12.1 - Online backup to Google Dri...
Arq is super-easy online backup for the Mac. Back up to your own Google Drive storage (15GB free storage), your own Amazon Glacier ($.01/GB per month storage) or S3, or any SFTP server. Arq backs up... Read more
Gutenprint 5.2.11-pre1 - Quality drivers...
Gutenprint is a suite of printer drivers that may be used with most common UNIX print spooling systems, including CUPS, lpr, LPRng, or others. Gutenprint currently supports over 2000 printer models.... Read more

Vector 2 is Officially a Thing and it...
Vector is a pretty cool parkour-driven runner that's gotten a pretty decent following since it first came out - although personally I think more people could stand to show it some love. Anyway, Nekki has announced that a sequel isofficially on its... | Read more »
This Week at 148Apps:June 22-26, 2015
June's Summer Journey Continues With 148Apps How do you know what apps are worth your time and money? Just look to the review team at 148Apps. We sort through the chaos and find the apps you're looking for. The ones we love become Editor’s Choice,... | Read more »
LEGO® Minifigures Online (Games)
LEGO® Minifigures Online 1.0.1 Device: iOS iPhone Category: Games Price: $4.99, Version: 1.0.1 (iTunes) Description: | Read more »
World of Tanks Blitz celebrates its firs...
Today marks the first anniversary of the launch of World of Tanks Blitz, the mobile version of the PC tank battler, World of Tanks. World of Tanks Blitz launched on iOS and Android on June 26th last year and to celebrate, Wargaming is giving all... | Read more »
Heroes and Castles 2 Has its Own Standal...
Heroes and Castles 2 is a third-person castle defense game from the same team behind Block Fortress and Bug Heroes. It's cool, it's fun, and now it has its very own free version. [Read more] | Read more »
Formula Cartoon All-Stars Lets You Race...
Ever want to pit your favorite characters from shows like Steven Universe, Adventure Time, and Regular Show against each other in a not quite death race? Well once upon a time you could, but Formula All Stars Touch N' Go doesn't exist anymore. Hope... | Read more »
Retype - Typography Photo Editor (Photo...
Retype - Typography Photo Editor 1.0 Device: iOS Universal Category: Photography Price: $2.99, Version: 1.0 (iTunes) Description: Retype is built out of passion for great typography and it's all about adding text to photo with style... | Read more »
Hungry Shark Evolution Celebrates Shark...
Shark Week is almost here, as is Independence Day, so naturally Hungry Shark Evolution is going to get in on the action. Yes, even the fireworks. [Read more] | Read more »
The New Trivia Crack Will Feature a Musi...
It's official: iHeartMedia (you may know them from iHeartRadio) will be in charge of providing music-related questions for Trivia Crack's upcoming sequel. Also Trivia Crack is getting a sequel. [Read more] | Read more »
Toca Life: City (Education)
Toca Life: City 1.0 Device: iOS Universal Category: Education Price: $2.99, Version: 1.0 (iTunes) Description: Welcome to Toca Life: City, a metropolis filled with everyday fun! Customize characters, explore exciting locations and... | Read more »

Price Scanner via MacPrices.net

OtterBox Releases New Symmetry Series Metalli...
Otterbox’s new Symmetry Series of smartphone cases flaunts the best of both both street style and street smarts with their new metallic finishes and trusted OtterBox protection for iPhone 6 and... Read more
MacBook Airs on sale for up to $75 off MSRP
Save up to $75 on the purchase of a new 2015 13″ or 11″ 1.6GHz MacBook Air at the following resellers. Shipping is free with each model: 11" 128GB MSRP $899 11" 256GB... Read more
Apple’s Education discount saves up to $300 o...
Purchase a new Mac or iPad at The Apple Store for Education and take up to $300 off MSRP. All teachers, students, and staff of any educational institution qualify for the discount. Shipping is free,... Read more
Save up to $600 with Apple refurbished Mac Pr...
The Apple Store has Apple Certified Refurbished Mac Pros available for up to $600 off the cost of new models. An Apple one-year warranty is included with each Mac Pro, and shipping is free. The... Read more
Mac Pros on sale for up to $260 off MSRP
B&H Photo has Mac Pros on sale for up to $260 off MSRP. Shipping is free, and B&H charges sales tax in NY only: - 3.7GHz 4-core Mac Pro: $2799, $200 off MSRP - 3.5GHz 6-core Mac Pro: $3719.99... Read more
Save up to $400 on 2014 15-inch Retina MacBoo...
B&H Photo has previous-generation 2014 15″ Retina MacBook Pros on sale for up to $400 off original MSRP. Shipping is free, and B&H charges NY sales tax only: - 15″ 2.2GHz Retina MacBook Pro... Read more
15-inch Retina MacBook Pros on sale for up to...
B&H Photo has new 2015 15″ Retina MacBook Pros on sale for up to $125 off MSRP including free shipping plus NY sales tax only: - 15″ 2.2GHz Retina MacBook Pro: $1899.99 $100 off - 15″ 2.5GHz... Read more
College Student Deals: Additional $100 off Ma...
Take an additional $100 off all MacBooks and iMacs at Best Buy Online with their College Students Deals Savings, valid through July 11, 2015. Anyone with a valid .EDU email address can take advantage... Read more
Apple refurbished Time Capsules available for...
The Apple Store has certified refurbished Time Capsules available for $100 off MSRP. Apple’s one-year warranty is included with each Time Capsule, and shipping is free: - 2TB Time Capsule: $199, $100... Read more
Newsweek Launches iPhone App
The venerable weekly news magazine Newsweek, owned by IBT Media, has announced the launch of its first iPhone app. The new app is available through Apple’s App Store and will allow consumers to read... Read more

Jobs Board

*Apple* TV Live Streaming Frameworks Test En...
**Job Summary** Work and contribute towards the engineering of Apple 's state-of-the-art products involving video, audio, and graphics in Interactive Media Group (IMG) at Read more
Project Manager, WW *Apple* Fulfillment Ope...
…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
Senior Data Scientist, *Apple* Retail - Onl...
**Job Summary** Apple Retail - Online sells Apple products to customers around the world. In addition to selling Apple products with unique services such as iPad Read more
*Apple* Music Producer - Apple (United State...
**Job Summary** Apple Music seeks a Producer to help shepherd some of the most important content and editorial initiatives within the music app, with a particular focus Read more
Sr. Technical Services Consultant, *Apple*...
**Job Summary** Apple Professional Services (APS) has an opening for a senior technical position that contributes to Apple 's efforts for strategic and transactional Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.