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

FotoMagico 5.6.12 - Powerful slideshow c...
FotoMagico lets you create professional slideshows from your photos and music with just a few, simple mouse clicks. It sports a very clean and intuitive yet powerful user interface. High image... Read more
OmniGraffle Pro 7.12.1 - 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
beaTunes 5.2.1 - Organize your music col...
beaTunes is a full-featured music player and organizational tool for music collections. How well organized is your music library? Are your artists always spelled the same way? Any R.E.M. vs REM?... Read more
HandBrake 1.3.0 - Versatile video encode...
HandBrake is a tool for converting video from nearly any format to a selection of modern, widely supported codecs. Features Supported Sources VIDEO_TS folder, DVD image or real DVD (unencrypted... Read more
Macs Fan Control 1.5.1.6 - Monitor and c...
Macs Fan Control allows you to monitor and control almost any aspect of your computer's fans, with support for controlling fan speed, temperature sensors pane, menu-bar icon, and autostart with... Read more
TunnelBear 3.9.3 - Subscription-based pr...
TunnelBear is a subscription-based virtual private network (VPN) service and companion app, enabling you to browse the internet privately and securely. Features Browse privately - Secure your data... Read more
calibre 4.3.0 - Complete e-book library...
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 librarian... Read more
Lyn 1.13 - Lightweight image browser and...
Lyn is a fast, lightweight image browser and viewer designed for photographers, graphic artists, and Web designers. Featuring an extremely versatile and aesthetically pleasing interface, it delivers... Read more
Visual Studio Code 1.40.0 - Cross-platfo...
Visual Studio Code provides developers with a new choice of developer tool that combines the simplicity and streamlined experience of a code editor with the best of what developers need for their... Read more
OmniGraffle 7.12.1 - Create diagrams, fl...
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

Latest Forum Discussions

See All

The House of Da Vinci 2 gets a new gamep...
The House of Da Vinci launched all the way back in 2017. Now, developer Blue Brain Games is gearing up to deliver a second dose of The Room-inspired puzzling. Some fresh details have now emerged, alongside the game's first official trailer. [Read... | Read more »
Shoot 'em up action awaits in Battl...
BattleBrew Productions has just introduced another entry into its award winning, barrelpunk inspired, BattleSky Brigade series. Whilst its previous title BattleSky Brigade TapTap provided fans with idle town building gameplay, this time the... | Read more »
Arcade classic R-Type Dimensions EX blas...
If you're a long time fan of shmups and have been looking for something to play lately, Tozai Games may have just released an ideal game for you on iOS. R-Type Dimensions EX brings the first R-Type and its sequel to iOS devices. [Read more] | Read more »
Intense VR first-person shooter Colonicl...
Our latest VR obsession is Colonicle, an intense VR FPS, recently released on Oculus and Google Play, courtesy of From Fake Eyes and Goboogie Games. It's a pulse-pounding multiplayer shooter which should appeal to genre fanatics and newcomers alike... | Read more »
PUBG Mobile's incoming update bring...
PUGB Mobile's newest Royale Pass season they're calling Fury of the Wasteland arrives tomorrow and with it comes a fair chunk of new content to the game. We'll be seeing a new map, weapon and even a companion system. [Read more] | Read more »
PSA: Download Bastion for free, but wait...
There hasn’t been much news from Supergiant Games on mobile lately regarding new games, but there’s something going on with their first game. Bastion released on the App Store in 2012, and back then it was published by Warner Bros. This Warner... | Read more »
Apple Arcade: Ranked - 51+ [Updated 11.5...
This is Part 2 of our Apple Arcade Ranking list. To see part 1, go here. 51. Patterned [Read more] | Read more »
NABOKI is a blissful puzzler from acclai...
Acclaimed developer Rainbow Train's latest game, NABOKI, is set to launch for iOS, Android, and Steam on November 13th. It's a blissful puzzler all about taking levels apart in interesting, inventive ways. [Read more] | Read more »
A Case of Distrust is a narrative-driven...
A Case of Distrust a narrative-focused mystery game that's set in the roaring 20s. In it, you play as a detective with one of the most private eye sounding names ever – Phyllis Cadence Malone. You'll follow her journey in San Francisco as she... | Read more »
Brown Dust’s October update offers playe...
October is turning out to be a productive month for the Neowiz team, and a fantastic month to be a Brown Dust player. First, there was a crossover event with the popular manga That Time I Got Reincarnated as a Slime. Then, there was the addition of... | Read more »

Price Scanner via MacPrices.net

Score a 37% discount on Apple Smart Keyboards...
Amazon has Apple Smart Keyboards for current-generation 10″ iPad Airs and previous-generation 10″ iPad Pros on sale today for $99.99 shipped. That’s a 37% discount over Apple’s regular MSRP of $159... Read more
Apple has refurbished 2019 13″ 1.4GHz MacBook...
Apple has a full line of Certified Refurbished 2019 13″ 1.4GHz 4-Core Touch Bar MacBook Pros available starting at $1099 and up to $230 off MSRP. Apple’s one-year warranty is included, shipping is... Read more
2019 13″ 1.4GHz 4-Core MacBook Pros on sale f...
Amazon has new 2019 13″ 1.4GHz 4-Core Touch Bar MacBook Pros on sale for $150-$200 off Apple’s MSRP. These are the same MacBook Pros sold by Apple in its retail and online stores: – 2019 13″ 1.4GHz/... Read more
11″ 64GB Gray WiFi iPad Pro on sale for $674,...
Amazon has the 11″ 64GB Gray WiFi iPad Pro on sale today for $674 shipped. Their price is $125 off MSRP for this iPad, and it’s the lowest price available for the 64GB model from any Apple reseller. Read more
2019 15″ MacBook Pros available for up to $42...
Apple has a full line of 2019 15″ 6-Core and 8-Core Touch Bar MacBook Pros, Certified Refurbished, available for up to $420 off the cost of new models. Each model features a new outer case, shipping... Read more
2019 15″ MacBook Pros on sale this week for $...
Apple resellers B&H Photo and Amazon are offering the new 2019 15″ MacBook Pros for up to $300 off Apple’s MSRP including free shipping. These are the same MacBook Pros sold by Apple in its... Read more
Sunday Sale: AirPods with Wireless Charging C...
B&H Photo has Apple AirPods with Wireless Charging Case on sale for $159.99 through 11:59pm ET on November 11th. Their price is $40 off Apple’s MSRP, and it’s the lowest price available for these... Read more
Details of Sams Club November 9th one day App...
Through midnight Saturday night (November 9th), Sams Club online has several Apple products on sale as part of their One Day sales event. Choose free shipping or free local store pickup (if available... Read more
Sprint is offering the 64GB Apple iPhone 11 f...
Sprint has the new 64GB iPhone 11 available for $15 per month for new lines. That’s about 50% off their standard monthly lease of $29.17. Over is valid until November 24, 2019. The fine print: “Lease... Read more
New Sprint November iPhone deal: Lease one iP...
Switch to Sprint and purchase an Apple iPhone 11, 11 Pro, or 11 Pro Max, and get a second 64GB iPhone 11 for free. Requires 2 new lines or 1 upgrade-eligible line and 1 new line. Offer is valid from... Read more

Jobs Board

*Apple* Mobility Pro - Best Buy (United Stat...
**746087BR** **Job Title:** Apple Mobility Pro **Job Category:** Store Associates **Store NUmber or Department:** 000319-Harlem & Irving-Store **Job Description:** Read more
Best Buy *Apple* Computing Master - Best Bu...
**743392BR** **Job Title:** Best Buy Apple Computing Master **Job Category:** Store Associates **Store NUmber or Department:** 001171-Southglenn-Store **Job Read more
Best Buy *Apple* Computing Master - Best Bu...
**746015BR** **Job Title:** Best Buy Apple Computing Master **Job Category:** Sales **Store NUmber or Department:** 000372-Federal Way-Store **Job Description:** Read more
*Apple* Mobility Pro - Best Buy (United Stat...
**744658BR** **Job Title:** Apple Mobility Pro **Job Category:** Store Associates **Store NUmber or Department:** 000586-South Hills-Store **Job Description:** At Read more
Best Buy *Apple* Computing Master - Best Bu...
**741552BR** **Job Title:** Best Buy Apple Computing Master **Job Category:** Sales **Store NUmber or Department:** 000277-Metcalf-Store **Job Description:** **What Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.