TweetFollow Us on Twitter

Oct 97 - Getting Started

Volume Number: 13 (1997)
Issue Number: 10
Column Tag: Getting Started

OPENSTEP Localization

by Dave Mark, ©1997, All Rights Reserved

One of the strengths of the Mac OS is the way it handles localization. For example, pulling the strings out of your application and storing them as resources makes the app relatively simple to translate into another language. Of course there's more to localization than that, but the point is, the Mac OS supports an underlying mechanism that makes localization possible. Fortunately, OPENSTEP (and presumably Rhapsody) features a similar mechanism that greatly simplifies the localization process.

A Localization Example

Let's start off with a look at an existing application that takes advantage of the OPENSTEP localization mechanism.

  • In the Workspace, navigate into the directory:
/NextDeveloper/Examples/AppKit/TextEdit/English.lproj

These files are all part of the TextEdit ProjectBuilder project. Among the files in this directory, you'll find a series of nib files including one named FindPanel.nib. Each nib file implements a portion of the user interface. For example, the file Info.nib contains the specs for the TextEdit info panel (NeXTSpeak for about box).FindPanel.nib contains the specs for the Find panel.

In the same directory, you'll also notice a pair of files named Localizable.strings and FindPanel.strings. The collection of .strings files act as a repository for all the text strings embedded in the TextEdit source code. These files are created at build-time in response to a set of function calls you'll place in your code. Before we get to the functions, take a closer look at these files.

  • Double-click on the file Localizable.strings.

The file will open in Edit. As you scroll through the file, you'll notice that it consists of pairs of C comments and assignment statements. Here's an example:

/* Menu item to make the current document rich text */
"&Make Rich Text" = "&Make Rich Text";

Though this may look like some sick C code, this is really just a database of strings, where each entry consists of a comment, followed by a left side and right side pair of strings. The left side is the default string, which you'll specify in your code. The right side is the version of this string used by this particular language. This example specifies the text to use in the TextEdit menu item that specifies RTF (rich text format). The left side is the string that appeared in the source code, presumably done in the native language of the programmer. The right string is the localized string. Since we are in the directory English.lproj, the right string is in English.

One localization approach kicks in once you've done your final project build. Once your source is frozen, you duplicate the English.lproj directory, creating a copy for each foreign language you plan on supporting. For example, you might make a copy of English.lproj named German.lproj. You'd then hand this directory to your German translator. The German translator would step through each of the .strings files, translating all the right-hand strings in each of the assignment statements to German.

When you ship your application, you'll actually ship an accompanying directory that includes all your XXX.lproj subdirectories. When the user specifies their preferred language using the Preferences application, then runs your application, the system uses the .lproj directory that matches the current language. So on an English system, the strings in English.lproj will be used. On a German system, the German.lproj strings will be used. Of course, you don't have to support multiple languages, but since localization is so easy to do, you'll likely want to consider supporting more than just your native language.

An Existing Localized Example

Let's take a look at a shipping application that supports more than one language.

  • In the Workspace, point your browser to the /NextDeveloper/Demos directory.

A series of applications will appear in the directory (Figure 1). As you'd expect, if you double-click on any of these, they'll run. These .App files are known as "application wrappers". They hide the underlying directory structure that ships with your application and makes them appear as a single application file. The Workspace does give you a way to view this accompanying directory.

Figure 1. The /NextDeveloper/Demos directory.

  • In the File Viewer, click on TextEdit.App to select it.
  • Select Open as Folder from the Workspace's File menu.

A new File Viewer will appear, showing you the directory structure beneath the TextEdit.app application wrapper (Figure 2). At the top level of this directory is a directory named Resources. The XXX.lproj directories live inside this directory. Each of the XXX.lproj directories contains localized versions of the FindPanel.strings and Localizable.strings files.

Figure 2. TextEdit.App, opened as a folder instead of as an application.

Take some time to look at some other directories and applications. Check out some of the other applications in /NextDeveloper/Demos. Check out /NextDeveloper/Apps and /NextApps. Note that some of the applications are localized, others are not. Some are only partially localized. Some feature a Resources directory, othersplace their XXX.lproj directories one level higher, directly in the app's main directory. This last is a clue to the version of ProjectBuilder used to create the application. The Project Builder that shipped with OPENSTEP 4.0 was the first version to embed the XXX.lproj directories in a Resources directory.

A Simple Example

Let's use ProjectBuilder to build a simple application, then localize it.

  • Launch ProjectBuilder, then select New from the Project menu.
  • When the New Project panel appears, select Application from the Project Type popup men, type the name Foo into the Name field, then click OK.
  • In ProjectBuilder's browser, under Interfaces, double-click on NEXTSTEP_Foo.nib (assuming you are running under NextStep -- otherwise, double-click on your appropriate nib file).

You will now find yourself in InterfaceBuilder. As you've seen in past columns, InterfaceBuilder provides your application with a default window named My Window. We'll add a button and a static text item to this window, then localize the text associated with these two items, just to see localization in action. After that, we'll take a look at the functions that bring localization to life.

  • In InterfaceBuilder, select Palettes from the Tools menu, Palettes submenu.
  • When the Palettes window appears, click on the Views icon.
  • Drag a static text item (the text in the palette says "Title") into "My Window".
  • Double-click on the static text item and change the text to read:
This application allows you to control a vehicle on another planet
  • Go back to the Palettes window and drag a button into the window.
  • Double-click on the button and change the text to say OK.
  • Select Save from the Document menu.
  • Quit InterfaceBuilder.
  • Back in ProjectBuilder, click on the hammer icon to bring up the Project Build window.
  • Click on the hammer icon in the Project Build window to start the build process.

You should get a message that says build succeeded.

  • Quit ProjectBuilder.

Now we'll run the app, just to verify that our window appears with its static text and button. Once we know the app runs, we'll localize it in German, set the system prefs to German, then run the app again showing the German localization at work.

  • * In the workspace, find the file Foo.app (it'll be inside the Foo folder you created when you first built the ProjectBuilder project).
  • * Double-click Foo.app.

The window should appear containing our static text and button (Figure 3).

Figure 3. Foo.app, before localization.

  • Quit Foo.app.

In the workspace, select Foo.app, then select Open as Folder from the File menu.

  • In the Foo.app file viewer, open the Resources directory, select English.lproj, then select Duplicate from the File menu.
  • Rename the duplicate to German.lproj.
  • Inside the German.lproj directory, Double-click NEXTSTEP_foo.nib.

You'll find yourself in InterfaceBuilder, editing the version of the nib file that lives in German.proj.

  • In InterfaceBuilder, edit the static text in the main window and change it to read:
Diese anwendung erlaubt es ihnen ein fahrzeug auf einem anderen planeten

Big thanks to Andreas Hommel, compiler writer extraordinaire, for the German translation! ;)

  • Save, then Quit InterfaceBuilder.

Note that we didn't change the button text. As it turns out, OK in German is OK! Our next step is to run the preferences application and change the order of preferred languages so that German is first.

  • Double-click on the Preferences application (it's the icon in the dock that looks like a clock).
  • In the Preferences window, click on the left-most icon (the one that looks like a series of flags).
  • In the scrolling list of Languages, click on Deutsch and drag it to the top of the list (Figure 4).

Figure 4. The Localization Preferences, with German (Deutsch) selected as the preferred language.

The scrolling list of languages allow you to order the set of languages on your machine. On my machine, I have it set to German first (just for this demo), then English, French, Italian, and Swedish. When I run an application on my machine, the order of languages in my preferences determine which .lproj directory is used to fetch the application's nib files. In this case, the directory German.lproj is used first, then English.lproj, French.lproj, etc.

  • Quit the Preferences application.
  • Go back into the file viewer and run Foo.App.

This time, the text should appear in German (Figure 5). Wunderbar!

Figure 5. Foo.app running in German. Cool!

The Localization Functions

The sample program we just created was relatively simple. All localization was done directly in the nib file. Earlier in the column, we explored the TextEdit application and saw that the TextEdit text strings were stored in a set of .strings files. Instead of editing the TextEdit nib files, localization was done on these .strings files. This is made possible by a set of localization functions called by your program any time it needs to access a localized string. The functions go out to the appropriate .strings file and retrieve the localized version of the specified string.

The three localization functions we're referring to all start with the name NSLocalizedString. Here's a cool trick you can use to search for routines in the precompiled headers used by your projects.

  • Launch the Edit application.
  • Type the text NSLocalizedString.
  • select the text, then select the Services menu, Header Viewer submenu, Find item (Alt-Shift-H).

The HeaderViewer app will do a search and find the selected routine in the various precompiled headers (in HeaderViewer, select Info/Preferences to see the list of precompiled headers to be searched). When we used this technique to search for NSLocalizedString we get:

#define NSLocalizedString(key, comment) \
_  [[NSBundle mainBundle] localizedStringForKey:(key) value:@"" table:nil]
#define NSLocalizedStringFromTable(key, tbl, comment) \
_  [[NSBundle mainBundle] localizedStringForKey:(key) value:@"" table:(tbl)]
#define NSLocalizedStringFromTableInBundle(key, tbl, bundle, comment) \
_  [bundle localizedStringForKey:(key) value:@"" table:(tbl)]

These three routines are the keys to localizing your strings.

NSLocalizedString takes a key and a comment, both of which are NSStrings. When ProjectBuilder encounters a call of NSLocalizedString, it uses the key and comment to build an entry in the file Localizable.strings. Here's an example:

NSString *untitled = NSLocalizedString(@"UNTITLED",
		@"Name of new, untitled document");

This piece of code defines an NSString pointer named untitled, which gets the string retrieved by the call of NSLocalizedString. The NSLocalizedString call takes two parameters, both of them NSStrings. The first one is the default value of the string. In this case, the default value is "UNTITLED". The second NSString is the comment that leads off the entry. ProjectBuilder will use this line of code to generate this entry in the file Localizable.strings:

/* Name of new, untitled document */
"&UNTITLED" = "&UNTITLED";

Note that the first parameter to NSLocalizedString serves as both the left and right side of the pseudo-assignment statement. Instead of embedding the string @"UNTITLED" directly in your code, pass it as a parameter to NSLocalizedString (or one of the other routines we'll look at in a sec), then use the NSString returned by NSLocalizedString instead. Think of NSLocalizedString as a bottleneck routine. By using it, your strings will automatically be exported into a .strings file. Once your strings are exported into a .strings file, you can hand the file to your translator, then place the localized copy in the appropriate XXX.lproj directory. Remember to tell your translator to translate the right hand side of all the assignment statements only. The left side provides the link to the NSLocalizedString call in your code. If your default language is English, the left side of the assignment statement in each .strings file will also be in English, as will all the first parameters to NSLocalizedString. The right side of each assignment statement might be in German, French, Swedish, Kanji, whatever.

By the way, though the comment and assignment statement might look like straight C code, it is actually intended as an NSStringTable. Just thought you'd like to know.

The function NSLocalizedStringFromTable takes a key, table name, and comment. key and comment serve the same purpose they did with NSLocalizedString. The table name is an NSString that specifies the name of an NSStringTable in which you'd like this entry stored. For example, this call will create an entry in the file FindPanel.strings.

NSString *untitled = NSLocalizedStringFromTable(
	@"Enter Find String:",
	@"FindPanel",
	@"Prompt for Find panel");

Why not stick all your strings in Localizable.strings? One approach used by OPENSTEP programmers is to create one .strings file for each panel/window in their interface. If your application supported a Find panel, an Info panel, and a main window, you might have three .strings files: FindPanel.strings, InfoPanel.strings, and MainPanel.strings. You might choose to keep all your strings in Localizable.strings or not use Localizable.strings at all. The point is, NSLocalizedStringFromTable is designed to let you store strings in the .strings file you choose.

The second parameter to NSLocalizedStringFromTable assumes the .strings suffix. So passing in the NSString @"FindPanel" will store the string in the file FindPanel.strings. Of course, if you create more than one .strings file, you'll have more files to manage and to pass on to your translator, so make the design choice that's right for your situation.

Terminology note: @"mystring" asks the runtime to create a temporary NSString object with the specified string and pass the reference to wherever it is used.

Finally, NSLocalizedStringFromTableInBundle lets you do the above but from a table associated with a bundle. Bundles are like plugins -- we'll get to them in a future column.

Till Next Month...

Your homework for this month: Add some NSLocalizedString calls to the VerySimpleText application that we built two months ago. You can add the code to the AboutWindowController class, inside the show method. Check out the .strings files generated by ProjectBuilder in response to your additional code. Do you see when these files get generated?

In Digital Librarian, open the bookshelf /NextLibrary/Bookshelves/DevTools.bshlf. Spend some time with this bookshelf, and pay special attention to Part 2: Creating the Interface. It has documents that describe creating a nib file, creating menus, initializing text, and tons more.

See you next month!

 
AAPL
$102.99
Apple Inc.
+0.52
MSFT
$44.38
Microsoft Corpora
-0.50
GOOG
$532.71
Google Inc.
+6.17

MacTech Search:
Community Search:

Software Updates via MacUpdate

OmniOutliner 4.1.3 - Organize your ideas...
OmniOutliner is a flexible program for creating, collecting, and organizing information. Give your creativity a kick start by using an application that's actually designed to help you think. It's... Read more
BBEdit 11.0 - Powerful text and HTML edi...
BBEdit is the leading professional HTML and text editor for the Mac. Specifically crafted in response to the needs of Web authors and software developers, this award-winning product provides a... Read more
Apple Security Update 2014-005 - For OS...
Apple Security Update is recommended for all users and improves the security of Mac OS X. For information on the security content of this update, please visit this website: http://support.apple.com/... Read more
EyeTV 3.6.6 - Watch and record TV on you...
EyeTV brings a rich TV experience to your Mac. Watch live TV on your Mac. Pause, rewind, and record whenever you want. EyeTV gives you powerful control over what you watch and how you watch it. Put... Read more
RapidWeaver 6.0 - Create template-based...
RapidWeaver is a next-generation Web design application to help you easily create professional-looking Web sites in minutes. No knowledge of complex code is required, RapidWeaver will take care of... Read more
NTFS 12.0.39 - Provides full read and wr...
Paragon NTFS breaks down the barriers between Windows and OS X. Paragon NTFS effectively solves the communication problems between the Mac system and NTFS, providing full read and write access to... Read more
RestoreMeNot 2.0.3 - Disable window rest...
RestoreMeNot provides a simple way to disable the window restoration for individual applications so that you can fine-tune this behavior to suit your needs. Please note that RestoreMeNot is designed... Read more
Command-C 1.1.5 - Clipboard sharing tool...
Command-C is a revolutionary app which makes easy to share your clipboard between iOS and OS X using your local WiFi network, even if the app is not currently opened. Copy anything (text, pictures,... Read more
Macgo Blu-ray Player 2.10.9.1750 - Blu-r...
Macgo Mac Blu-ray Player can bring you the most unforgettable Blu-ray experience on your Mac. Overview Macgo Mac Blu-ray Player can satisfy just about every need you could possibly have in a Blu-ray... Read more
Apple iOS 8.1 - The latest version of Ap...
The latest version of iOS can be downloaded through iTunes. Apple iOS 8 comes with big updates to apps you use every day, like Messages and Photos. A whole new way to share content with your family.... Read more

Latest Forum Discussions

See All

Fighting Fantasy: Caverns of the Snow Wi...
Fighting Fantasy: Caverns of the Snow Witch 1.0 Device: iOS Universal Category: Games Price: $5.99, Version: 1.0 (iTunes) Description: Travel to Northern Allansia’s perilous Icefinger Mountains to defeat the wicked Snow Witch in this... | Read more »
TinType by Hipstamatic (Photography)
TinType by Hipstamatic 1.0 Device: iOS iPhone Category: Photography Price: $.99, Version: 1.0 (iTunes) Description: Create hauntingly beautiful, soul capturing portraits with TinType by Hipstamatic. Inspired by daguerreotypes,... | Read more »
The Latest Update for Heroes of Dragon A...
The Latest Update for Heroes of Dragon Age Introduces Daily PvE Challenges Posted by Ellis Spice on October 22nd, 2014 [ permalink ] | Read more »
A New Trailer has Been Revealed for Epic...
A New Trailer has Been Revealed for Epic of Kings Posted by Jessica Fisher on October 22nd, 2014 [ permalink ] Dead Mage Inc. has released a new, action-packed trailer for the upcoming Epic of Kings. | Read more »
Find the Line Review
Find the Line Review By Campbell Bird on October 22nd, 2014 Our Rating: :: INSLIDE THE LINESUniversal App - Designed for iPhone and iPad Tease out beautiful line drawings in this unique, free-to-play puzzle game.   | Read more »
The Silent Age Episode 2 Review
The Silent Age Episode 2 Review By Jennifer Allen on October 22nd, 2014 Our Rating: :: ROUNDING THINGS OFF NICELYUniversal App - Designed for iPhone and iPad Rounding off a great point and click adventure comes The Silent Age... | Read more »
Craft Your Own Mini-Games with Papercade
Craft Your Own Mini-Games with Papercade Posted by Jessica Fisher on October 22nd, 2014 [ permalink ] iPad Only App - Designed for the iPad Scrapbookers move over, Scrapgaming is the new thing. | Read more »
Reshape Review
Reshape Review By Jennifer Allen on October 22nd, 2014 Our Rating: :: SIMPLE SHAPESUniversal App - Designed for iPhone and iPad Match triangles together to form cubes in this fast-paced and twitchy game.   | Read more »
Miika (Games)
Miika 1.0.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0.0 (iTunes) Description: Miika is a beautiful 3D puzzle game based on camera perspectives combined with the use of optical illusions. Miika challenges... | Read more »
Infuse Pro (Photography)
Infuse Pro 3.0 Device: iOS Universal Category: Photography Price: $9.99, Version: 3.0 (iTunes) Description: ** All-new version 3 includes fully licensed and certified DTS® and DTS-HD® audio! ** | Read more »

Price Scanner via MacPrices.net

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
iPad Air 2 & iPad mini 3 Best Tablets Yet...
The new iPads turned out to be pretty much everything I’d been hoping for and more than I’d expected.”More” particularly in terms of a drinking-from-a-firehose choice of models and configurations,... Read more
Drafts 4 Reinvents iOS Productivity App
N Richland Hills, Texas based Agile Tortoise has announced the release of Drafts 4 for iPhone and iPad. Drafts is a quick capture note taking app with flexible output actions. Drafts 4 scales from... Read more
AT&T accepting preorders for new iPads fo...
AT&T Wireless is accepting preorders for the new iPad Air 2 and iPad mini 3, cellular models, for $100 off MSRP with a 2-year service agreement: - 16GB iPad Air 2 WiFi + Cellular: $529.99 - 64GB... Read more
Apple offering refurbished Mac Pros for up to...
The Apple Store is offering Apple Certified Refurbished 2013 Mac Pros 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
Select MacBook Airs $100 off MSRP, free shipp...
B&H Photo has 2014 a couple of MacBook Airs on sale for $100 off MSRP. Shipping is free, and B&H charges NY sales tax only. They also include free copies of Parallels Desktop and LoJack for... Read more
13-inch 2.5GHz MacBook Pro on sale for $100 o...
B&H Photo has the 13″ 2.5GHz MacBook Pro on sale for $999.99 including free shipping plus NY sales tax only. Their price is $100 off MSRP. Read more
Strong iPhone, Mac And App Store Sales Drive...
Apple on Monday announced financial results for its fiscal 2014 fourth quarter ended September 27, 2014. The Company posted quarterly revenue of $42.1 billion and quarterly net profit of $8.5 billion... Read more
Apple Posts How-To For OS X Recovery
OS X 10.7 Lion and later include OS X Recovery. This feature includes all of the tools you need to reinstall OS X, repair your disk, and even restore from a Time Machine backup. OS X Recovery... Read more
Mac OS X Versions (Builds) Supported By Vario...
Apple Support has posted a handy resource explaining which Mac OS X versions (builds) originally shipped with or are available for your computer via retail discs, downloads, or Software Update. Apple... Read more

Jobs Board

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
Position Opening at *Apple* - Apple (United...
…customers purchase our products, you're the one who helps them get more out of their new Apple technology. Your day in the Apple Store is filled with a range of Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.