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!

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

OmniGraffle Pro 7.2.2 - 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
OmniGraffle 7.2.2 - Create diagrams, flo...
OmniGraffle helps you draw beautiful diagrams, family trees, flow charts, org charts, layouts, and (mathematically speaking) any other directed or non-directed graphs. We've had people use Graffle to... Read more
Spotify 1.0.44.100. - Stream music, crea...
Spotify is a streaming music service that gives you on-demand access to millions of songs. Whether you like driving rock, silky R&B, or grandiose classical music, Spotify's massive catalogue puts... Read more
Microsoft OneNote 15.29 - Free digital n...
OneNote is your very own digital notebook. With OneNote, you can capture that flash of genius, that moment of inspiration, or that list of errands that's too important to forget. Whether you're at... Read more
WALTR 2 2.0.8 - $39.95
WALTR 2 helps you wirelessly drag-and-drop any music, ringtones, videos, PDF, and ePub files onto your iPhone, iPad, or iPod without iTunes. It is the second major version of Softorino's critically-... Read more
Dropbox 16.3.27 - Cloud backup and synch...
Dropbox is an application that creates a special Finder folder that automatically syncs online and between your computers. It allows you to both backup files and keep them up-to-date between systems... Read more
EtreCheck 3.1.5 - For troubleshooting yo...
EtreCheck is an app that displays the important details of your system configuration and allow you to copy that information to the Clipboard. It is meant to be used with Apple Support Communities to... Read more
Carbon Copy Cloner 4.1.12 - Easy-to-use...
Carbon Copy Cloner backups are better than ordinary backups. Suppose the unthinkable happens while you're under deadline to finish a project: your Mac is unresponsive and all you hear is an ominous,... Read more
VueScan 9.5.62 - 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
SpamSieve 2.9.27 - Robust spam filter fo...
SpamSieve is a robust spam filter for major email clients that uses powerful Bayesian spam filtering. SpamSieve understands what your spam looks like in order to block it all, but also learns what... Read more

Latest Forum Discussions

See All

Track Santa with these three festive app...
Christmas is fast approaching and that means it's time to prepare for Santa's yearly pilgrimage around the globe. Christmas Eve is an exciting time as parents help their kids get ready to welcome Santa. You've got the cookies and milk all planned... | Read more »
Galaxy on Fire 3 and four other fantasti...
Galaxy on Fire 3 - Manticore brings the series back for another round of daring space battles. It's familiar territory for folks who are familiar with the franchise. If you've beaten the game and are looking to broaden your horizons, might we... | Read more »
The best apps for your holiday gift exch...
What's that, you say? You still haven't started your holiday shopping? Don't beat yourself up over it -- a lot of people have been putting it off, too. It's become easier and easier to procrastinate gift shopping thanks to a number of apps that... | Read more »
Toca Hair Salon 3 (Education)
Toca Hair Salon 3 1.0 Device: iOS Universal Category: Education Price: $2.99, Version: 1.0 (iTunes) Description: | Read more »
Winter comes to Darkwood as Seekers Note...
MyTona, based in the chilly Siberian city of Yakutsk, has brought a little festive fun to its hidden object game Seekers Notes: Hidden Mystery. The Christmas update introduces some new inhabitants to players, and with them a chance to win plenty of... | Read more »
Bully: Anniversary Edition (Games)
Bully: Anniversary Edition 1.03.1 Device: iOS Universal Category: Games Price: $6.99, Version: 1.03.1 (iTunes) Description: *** PLEASE NOTE: This game is officially supported on the following devices: iPhone 5 and newer, iPod Touch... | Read more »
PINE GROVE (Games)
PINE GROVE 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: A pine grove where there are no footsteps of people due to continuous missing cases. The case is still unsolved and nothing has... | Read more »
Niantic teases new Pokémon announcement...
After rumors started swirling yesterday, it turns out there is an official Pokémon GO update on its way. We’ll find out what’s in store for us and our growing Pokémon collections tomorrow during the Starbucks event, but Niantic will be revealing... | Read more »
3 reasons why Nicki Minaj: The Empire is...
Nicki Minaj is as business-savvy as she is musically talented and she’s proved that by launching her own game. Designed by Glu, purveyors of other fine celebrity games like cult favorite Kim Kardashian: Hollywood, Nicki Minaj: The Empire launched... | Read more »
Clash of Clans is getting its own animat...
Riding on its unending wave of fame and success, Clash of Clans is getting an animated web series based on its Clash-A-Rama animated shorts.As opposed to the current shorts' 60 second run time, the new and improved Clash-A-Rama will be comprised of... | Read more »

Price Scanner via MacPrices.net

New 2016 13-inch Touch Bar MacBook Pros on sa...
B&H Photo the new 2016 Apple 13″ 2.9GHz/256GB Touch Bar MacBook Pros on sale for $50 off MSRP, each including free shipping plus NY sales tax only: - 13″ 2.9GHz/256GB Touch Bar MacBook Pro Space... Read more
12-inch 1.2GHz Space Gray Retina MacBook on s...
B&H Photo has dropped their price on the 2016 Apple 12″ 1.2GHz Space Gray Retina MacBook (MLH82LL/A) to $1399 including free shipping plus NY sales tax only. Their price is $200 off MSRP, and it’... Read more
Never Settle for Low Performing Wifi With iOS...
AppYogi Software has announced the release of WiFi Signal Strength Status App 1.0, the company’s new utility developed exclusively for macOS. WiFi Signal Strength Status App features a unique, single... Read more
New 2016 13-inch Touch Bar MacBook Pros in st...
B&H Photo has stock of new 2016 Apple 13″ Touch Bar MacBook Pro models, each including free shipping plus NY sales tax only: - 13″ 2.9GHz/512GB Touch Bar MacBook Pro Space Gray: $1999 - 13″ 2.... Read more
New 2016 15″ Touch Bar MacBook Pros in stock...
B&H Photo has new 2016 Apple 15″ Touch Bar MacBook Pro models in stock today including free shipping plus NY sales tax only: - 15″ 2.7GHz Touch Bar MacBook Pro Space Gray: $2799 - 15″ 2.7GHz... Read more
DietSensor App Targeting Diabetes and Obesity...
DietSensor, Inc., a developer of smart food and nutrition applications designed to fight diabetes and obesity and help improve overall fitness, has announced the launch of its DietSensor app for... Read more
Holiday 2016 13-inch 2.0GHz MacBook Pro sales...
B&H has the non-Touch Bar 13″ MacBook Pros in stock today for $50-$100 off MSRP. Shipping is free, and B&H charges NY sales tax only: - 13″ 2.0GHz MacBook Pro Space Gray (MLL42LL/A): $1449 $... Read more
Holiday sale: Apple TVs for $51-$40 off MSRP,...
Best Buy has dropped their price on the 64GB Apple TV to $159.99 including free shipping. That’s $40 off MSRP. 32GB Apple TVs are on sale right now for $98 on Sams Club’s online store. That’s $51 off... Read more
12-inch Retina MacBooks, Apple refurbished, n...
Apple has restocked a full line of Certified Refurbished 2016 12″ Retina MacBooks, now available for $200-$260 off MSRP. Refurbished 2015 models are available starting at $929. Apple will include a... Read more
Holiday sale: 12-inch Retina MacBook for $100...
B&H has 12″ Retina MacBooks on sale for $100 off MSRP as part of their Holiday sale. Shipping is free, and B&H charges NY sales tax only: - 12″ 1.1GHz Space Gray Retina MacBook: $1199 $100... Read more

Jobs Board

Integration Technician, *Apple* - Zones, In...
…at Zones and for our customers each day. Position Overview The Apple Integration Technician will be responsible for performing customer specific configuration Read more
*Apple* Brand Ambassador (Macy's) - The...
…(T-ROC), is proud of its unprecedented relationship with our partner and client, APPLE ,in bringing amazing" APPLE ADVOCATES"to "non" Apple store locations. Read more
*Apple* Retail - Multiple Positions- Trumbul...
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 - Apple,...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
US- *Apple* Store Leader Program - Apple (Un...
…Summary Learn and grow as you explore the art of leadership at the Apple Store. You'll master our retail business inside and out through training, hands-on Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.