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
$100.75
Apple Inc.
+0.64
MSFT
$46.36
Microsoft Corpora
-0.08
GOOG
$577.36
Google Inc.
+1.00

MacTech Search:
Community Search:

Software Updates via MacUpdate

QuickBooks 2015 16.0.0.1352 R1 - Financi...
QuickBooks 2015 helps you manage your business easily and efficiently. Organize your finances all in one place, track money going in and out of your business, and spot areas where you can save.... Read more
Mac DVDRipper Pro 5.0.1 - Copy, backup,...
Mac DVDRipper Pro is the DVD backup solution that lets you protect your DVDs from scratches, save your batteries by reading your movies from your hard disk, manage your collection with just a few... Read more
Apple OS X bash Update 1.0 - Fix for sec...
The OS X bash Update fixes a security flaw in the bash UNIX shell on OS X 10.9.5 (also on OS X 10.8 and 10.7 [see Related Links below]). OS X 10.9.5 or later Downloads for OS X 10.8 and OS X 10.7 in... Read more
SyncTwoFolders 2.0.5 - Syncs two user-sp...
SyncTwoFolders simply synchronizes two folders. It supports synchronization across mounted network drives and it is a possibility to run a simulation showing in a log what will be done. Please visit... Read more
FinderPop 2.5.7 - Classic Mac utility, n...
FinderPop is a Universal preference pane that extends OS X's contextual menus using a FinderPop Items folder much as the Apple Menu Items folder used to do for the Apple menu. It has other features... Read more
VueScan 9.4.45 - 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
LibreOffice 4.3.2.2 - Free Open Source o...
LibreOffice is an office suite (word processor, spreadsheet, presentations, drawing tool) compatible with other major office suites. The Document Foundation is coordinating development and... Read more
calibre 2.4 - Complete e-library managem...
Calibre is a complete e-book library manager. Organize your collection, convert your books to multiple formats, and sync with all of your devices. Let Calibre be your multi-tasking digital... Read more
Default Folder X 4.6.9b1 - Enhances Open...
Default Folder X attaches a toolbar to the right side of the Open and Save dialogs in any OS X-native application. The toolbar gives you fast access to various folders and commands. You just click... Read more
Beamer 2.0.4 - Stream any movie file fro...
Beamer streams to your Apple TV.... Plays any movie file - Just like the popular desktop movie players, Beamer accepts all common formats, codecs and resolutions. AVI, MKV, MOV, MP4, WMV, FLV. To... Read more

Latest Forum Discussions

See All

WW2: Sandbox. Strategy & Tactics (G...
WW2: Sandbox. Strategy & Tactics 1.0.0 Device: iOS Universal Category: Games Price: $9.99, Version: 1.0.0 (iTunes) Description: Sandbox is the unlimited sequel to our Strategy & Tactics: World War II. We've abandoned... | Read more »
apeFilter (Music)
apeFilter 1.0 Device: iOS Universal Category: Music Price: $6.99, Version: 1.0 (iTunes) Description: | Read more »
Shred It! Review
Shred It! Review By Jennifer Allen on September 30th, 2014 Our Rating: :: GORGEOUS BUT BASICUniversal App - Designed for iPhone and iPad It might look lovely, but Shred It! is a pretty shallow endless runner/snowboarding game.   | Read more »
It Came From Canada: Angry Birds: Transf...
Anyone afraid that throwing Transformers into the Angry Birds mix would result in a Michael Bay-level of childhood pillaging can rest easy. While Rovio’s famous fowls may be a 21st century staple, Angry Birds: Transformers wears its affection for... | Read more »
Galaxy Trucker Review
Galaxy Trucker Review By Rob Thomas on September 30th, 2014 Our Rating: :: IN FOR THE LONG HAULiPad Only App - Designed for the iPad We got a great big convoy, rockin’ through the night… the endless night of outer space, that is.... | Read more »
Moon and Sun – children’s book Review
Moon and Sun – children’s book Review By Amy Solomon on September 30th, 2014 Our Rating: Moon and Sun is a fable-like children’s book with lush illustrations.   Developer: Marcio Monteiro Price: $3.99 Version: 1.0 App Reviewed on... | Read more »
Kairosoft Finally Brings The Pyraplex to...
Kairosoft Finally Brings The Pyraplex to iOS Posted by Jessica Fisher on September 30th, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Yeti’s Parole Officer Review
Yeti’s Parole Officer Review By Jennifer Allen on September 30th, 2014 Our Rating: Universal App - Designed for iPhone and iPad Yeti’s Parole Officer proves that looks aren’t everything in this entertaining, if plain, piece of... | Read more »
Record Keeper and World Wide Words – Two...
Record Keeper and World Wide Words – Two New Final Fantasy Games Arrive on iOS in Japan Posted by Ellis Spice on September 30th, 2014 [ permalink ] | Read more »
iPollute Review
iPollute Review By Nadia Oxford on September 30th, 2014 Our Rating: :: iPOLLUTE, uPOLLUTEUniversal App - Designed for iPhone and iPad iPollute is a delightful-looking pollution simulator, though it’s a bit light on “game” content... | Read more »

Price Scanner via MacPrices.net

Apple Boycotts German Magazine Computer Bild...
Apple has revoked its PR accreditation of Germany’s Computer Bild, Europe’s best-selling PC magazine, in reaction to Bild’s posting of a “#Bentgate” YouTube video. Axel Telzerow, editor in chief of... Read more
iPhone 6 & iPhone 6 Plus Available in Chi...
Apple has announced that iPhone 6 and iPhone 6 Plus will be available in China beginning Friday, October 17 from the Apple Online Store (http://www.apple.com), Apple’s retail stores, and an expansive... Read more
MacBook Airs on sale for $100 off MSRP, start...
Best Buy has the new 2014 MacBook Airs on sale for $100 off MSRP on their online store. Choose free home shipping or free local store pickup (if available). Prices valid for online orders only, in-... Read more
Apple Releases OS X Mavericks bash Update 1.0...
Apple has released a patch update for OS X Mavericks users to address the recently-detected “Shellshock” security bug in BSD UNIX’s bash shell. Apple says only a few Mac users who had manually... Read more
Pivotal Payments Ready for Apple Pay – FlexPo...
Pivotal Payments, a provider of merchant services and global payment processing solutions, has announced its proprietary FlexPoint platform will support credit and debit transactions through Apple’s... Read more
iStabilizer Announces Tabarm — First Friction...
iStabilizer, a specialist in universal lightweight compact tripods, steady cams, dollies, mounts, and remotes for smartphones, tablets, and cameras, announced today the iStabilizer tabArm, the first... Read more
IStabilizer Flex Smartphone Tripod Wins Usa T...
iStabilizer, a specialist in universal lightweight compact tripods, steady cams, and other products for smartphones, tablets, and cameras, has announced today that its iStabilizer Flex smartphone... Read more
13-inch 2.8GHz Retina MacBook Pro on sale for...
B&H Photo has the new 2014 13″ 2.8GHz Retina MacBook Pro on sale for $1699.99 including free shipping plus NY sales tax only. They’ll also include free copies of Parallels Desktop and LoJack for... Read more
15-inch Retina MacBook Pros on sale for up to...
B&H Photo has the new 2014 15″ Retina MacBook Pros on sale for up to $150 off MSRP. Shipping is free, and B&H charges NY sales tax only. They’ll also include free copies of Parallels Desktop... Read more
Get Down to Business On Your iPad With Free N...
Utah based Poem LLC has introduced Nexticy 1.0, a full-featured, affordable (Free) forms application for iPad. Nexticy makes it ‘way easy’ to create, store, retrieve and analyze paper-like forms of... Read more

Jobs Board

*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the 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
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
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.