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

Thunderbird 52.3.0 - Email client from M...
As of July 2012, Thunderbird has transitioned to a new governance model, with new features being developed by the broader free software and open source community, and security fixes and improvements... Read more
coconutBattery 3.6.3 - Displays info abo...
With coconutBattery you're always aware of your current battery health. It shows you live information about your battery such as how often it was charged and how is the current maximum capacity in... Read more
Little Snitch 4.0.2 - Alerts you about o...
Little Snitch gives you control over your private outgoing data. Track background activity As soon as your computer connects to the Internet, applications often have permission to send any... Read more
VueScan 9.5.82 - 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
Postbox 5.0.17 - Powerful and flexible e...
Postbox is a new email application that helps you organize your work life and get stuff done. It has all the elegance and simplicity of Apple Mail, but with more power and flexibility to manage even... Read more
CleanMyMac 3.8.6 - $39.95
CleanMyMac makes space for the things you love. Sporting a range of ingenious new features, CleanMyMac lets you safely and intelligently scan and clean your entire system, delete large, unused files... Read more
Default Folder X 5.1.6b3 - 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 on... Read more
Amazon Chime 4.6.5852 - Amazon-based com...
Amazon Chime is a communications service that transforms online meetings with a secure, easy-to-use application that you can trust. Amazon Chime works seamlessly across your devices so that you can... Read more
VOX 2.8.30 - Music player that supports...
VOX just sounds better! The beauty is in its simplicity, yet behind the minimal exterior lies a powerful music player with a ton of features and support for all audio formats you should ever need.... Read more
iFFmpeg 6.4.3 - Convert multimedia files...
iFFmpeg is a comprehensive media tool to convert movie, audio and media files between formats. The FFmpeg command line instructions can be very hard to master/understand, so iFFmpeg does all the hard... Read more

The best games we played this week - Aug...
Another busy week has come to a close. We played a lot of excellent games this week and now it's time to look back and reflect on some our favorites. Here are our picks for the week of August 18. [Read more] | Read more »
War Wings beginner's guide - how to...
War Wings is the newest project from well-established game maker Miniclip. It's a World War II aerial dogfighting game with loads of different airplane models to unlock and battle. The game offers plenty of single player and multiplayer action. We... | Read more »
How to win every 2v2 battle in Clash Roy...
2v2 is coming back to Clash Royale in a big way. Although it's only been available for temporary periods of time, 2v2 has seen a hugely positive fan response, with players clamoring for more team-based gameplay. Soon we'll get yet another taste of... | Read more »
Roll to Win with Game of Dice’s new upda...
Joycity’s hit Game of Dice gets a big new update this week, introducing new maps, mechanics, and even costumes. The update sets players loose on an exciting new map, The Cursed Tower, that allows folks to use special Runes mid-match. If you feel... | Read more »
Bottom of the 9th (Games)
Bottom of the 9th 1.0.1 Device: iOS iPhone Category: Games Price: $4.99, Version: 1.0.1 (iTunes) Description: Play the most exciting moment of baseball in this fast-paced dice and card game! | Read more »
The best apps for viewing the solar ecli...
If you somehow missed the news, many parts of the United States will be witness to a total solar eclipse on August 21 for the first time in over 90 years. It'll be possible to see the eclipse in at least some capacity throughout the continental U... | Read more »
The 5 best mobile survival games
Games like ARK: Survival Evolved and Conan Exiles have taken the world of gaming by storm. The market is now flooded with hardcore survival games that send players off into the game's world with nothing but maybe the clothes on their back. Never... | Read more »
Portal Walk (Games)
Portal Walk 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: Portal Walk is adventure and relaxing platform game about Eugene. Eugene stuck between worlds and trying to find way back home.... | Read more »
Technobabylon (Games)
Technobabylon 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: City of Newton, 2087. Genetic engineering is the norm, the addictive Trance has replaced almost any need for human interaction,... | Read more »
5 reasons why 2v2 is the best mode in Cl...
Supercell has been teasing fans with 2v2 windows that allow players to team up for limited periods of time. The Summer of 2v2 was just this past July, but players are already clamoring for more of that sweet, sweet team-based action. The fans have... | Read more »

Price Scanner via MacPrices.net

Back To School With The Edge Desk All-in-one...
Back to school is just around the corner, and the ergonomically correct Edge Desk all-in-one portable kneeling desk is ideal for students living in dorms and small apartments, Edge Desk features:... Read more
Norton Core Secure Wi-Fi Router Now Available...
First introduced at the 2017 Consumer Electronics Show (CES), Norton Core, a secure, high-performance Wi-Fi router, fundamentally changed the concept of Wi-Fi routers by making security the primary... Read more
ViewSonic Adds New 27-inch 4K UHD Monitor to...
ViewSonic Corp. has introduced the VP2785-4K, a 27-inch 4K UHD (3840×2160) monitor that delivers precise and consistent color representation and performance to ensure incredible image quality. Built... Read more
Apple now offering Certified Refurbished 2017...
Apple is now offering Certified Refurbished 2017 27″ iMacs for up to $350 off original MSRP. Apple’s one-year warranty is standard, and shipping is free. The following models are available: – 27″ 3.... Read more
13-inch 2.3GHz MacBook Pros on sale for $100...
Amazon has the new 2017 13″ 2.3GHz MacBook Pros on sale today for $100 off MSRP, each including free shipping: – 13″ 2.3GHz/128GB Space Gray MacBook Pro (MPXQ2LL/A): $1199.99 $100 off MSRP – 13″ 2.... Read more
Clearance 2016 13-inch MacBook Airs available...
B&H Photo has clearance 2016 13″ MacBook Airs available for up to $200 off original MSRP. Shipping is free, and B&H charges NY & NJ sales tax only: – 13″ 1.6GHz/128GB MacBook Air (MMGF2LL... Read more
Clearance 21-inch and 27-inch iMacs available...
B&H Photo has clearance 21″ and 27″ Apple iMacs available for up to $500 off original MSRP, each including free shipping plus NY & NJ sales tax only: – 27″ 3.3GHz iMac 5K: $1799 $500 off... Read more
New iOS 11 Productivity Features Welcome But...
The iOS community is in late summer holding mode awaiting the September arrival of the iPhone 8 and iOS 11. iOS 11 public betas have been available for months — number six was released this week —... Read more
Samsung Electronics Launches New Portable SSD...
Samsung Electronics America, Inc. has announced the launch of Samsung Portable SSD T5 – its newest portable solid state drive (PSSD) that raises the bar for the performance of external memory... Read more
TrendForce Reports YoY Gain of 3.6% for 2Q17...
Market research firm TrendForce reports that the global notebook shipments for this second quarter registered a sequential quarterly increase of 5.7% and a year-on-year increase of 3.6%, totaling 39.... Read more

Jobs Board

Development Operations and Site Reliability E...
Development Operations and Site Reliability Engineer, Apple Payment Gateway Job Number: 57572631 Santa Clara Valley, California, United States Posted: Jul. 27, 2017 Read more
Frameworks Engineering Manager, *Apple* Wat...
Frameworks Engineering Manager, Apple Watch Job Number: 41632321 Santa Clara Valley, California, United States Posted: Jun. 15, 2017 Weekly Hours: 40.00 Job Summary Read more
Business Development Manager - *Apple* Medi...
Job Summary Apple Music is a single, intuitive app that...- all in one place. You can stream any Apple Music song, playlist or album, and download it Read more
Development Operations and Site Reliability E...
Development Operations and Site Reliability Engineer, Apple Payment Gateway Job Number: 57572631 Santa Clara Valley, California, United States Posted: Jul. 27, 2017 Read more
Frameworks Engineering Manager, *Apple* Wat...
Frameworks Engineering Manager, Apple Watch Job Number: 41632321 Santa Clara Valley, California, United States Posted: Jun. 15, 2017 Weekly Hours: 40.00 Job Summary Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.