It was back in December of 2004 that I first considered the idea of internationalised (or internationalized for those in the US) documentation.

First, some terminology. Apple defines “Internationalisation” as “the process of designing and building an application to facilitate localization”. “Localisation”, in turn, is defined as “the cultural and linguistic adaptation of an internationalized application to two or more culturally-distinct markets”. The terms though are often used interchangeably.

So, internationalised documentation is documentation that has been localised for two or more culturally-distinct markets. That doesn’t really explain what I’m trying to do though – but we’ll get to that later.

Internationalised applications

Few Mac users realise that Applications in OS X can have localised display names. The name and extension of an Application is not necessarily the same as the name shown in the Finder (the display name).

For example, English speaking Mac users know that OS X comes with an Application called “Preview”. If you are a German speaker, you’ll see an Application called “Vorschau”. If you are using the Japanese language you’ll see “プレビュー”.

The underlying Application is still called “”. You can verify this by changing to another language, restarting the Finder (Force Quit it, for example), and finding the Preview application. Do a “Get Info” on the icon and examine the “Name & Extension”. Compare this with the display name shown in the finder.

So what is going on?

Mac OS X has an internationalisation framework that allows an application to have a localised display name. Within the application bundle that makes up is a folder Contents/Resources that has localised resources. In the “German.lproj” folder, for example, you find the file “InfoPlist.strings”. In this file you’ll find an entry:

CFBundleName = "Vorschau";

In simple terms, the Finder uses this as the display name for this application when the German language is being used (you can also use CFBundleDisplayName it appears, which would seem to make more sense).

Can we do this to documentation?

Unfortunately, this ability to localise display names only works with Applications. Most documents are not a bundle, but simply a flat file. Those that are a bundle (files that reside in directories with an extension of .rtfd are an example) don’t support localised display names.

However, we can build an Application that looks like a document, has localised display name, and opens the correct document for the current locale. In fact, I’ve made such an application available for download here.

I should point out, I wrote this application in January 2005. You’ll see from the link above that the result is not very user friendly for the developer, so I planned to write a GUI front end to make it easy to build Universal Documents. Unfortunately, time got away from me, and this application sat on my hard disk until recently. I’ve since found out that Apple have started doing something very similar (see the read me file on the iLife DVD). This made me decide not to attempt a GUI – it is quite possible Apple have something they’ll release to developers (if they haven’t already).

Internationalised Documentation

The idea is to basically use the internationalised application framework to open a particular document, based on locale. I wanted to make the code as simple as possible, so that internationalised documents weren’t huge files to download. The code I settled on was the following (there may be simpler ways):

//  main.m
//  Universal Document
//  Simple application with localised name that opens
//  documents contained within based on locale.
//  Created by Jamie Curmi on 30/01/05.
//  Copyright Jamie Curmi 2005. All rights reserved.

int main(int argc, char *argv[])
    NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];
    [[NSWorkspace sharedWorkspace] openURL: [NSURL fileURLWithPath:
        [[NSBundle mainBundle] pathForResource:
                @"OpenName", @"InfoPlist", nil) ofType:@""]]];

Basically, the OS X internationalisation framework handles the document name localisation, while the application’s main program finds the document to open (with key “OpenName”) and opens it.

Within the “document” bundle you have a “.lproj” folder for each language. For example, German.lproj. Names can also be based on Language and Regional Designations – for example “en_AU.lproj” for Australian English etc. See Apple’s Developer Documentation and the following list of codes for more information.

Within each “.lproj” folder you have a file called “InfoPlist.strings” – just as we had with internationalised applications. In this file you have two lines:

     CFBundleDisplayName = "Display Name of Document";
     OpenName = "Document Name.extension"; 

There is a bit of messing around to get the Finder to show changes while developing the documentation, but this gives you the general idea. See this link for a download of this application, and more instructions on how to set up your own.

So what have we achieved?

The following example will give you an idea of what we’ve now achieved.

A typical OS X installation DVD looks something like the following:

Using an internationalised document as described, we can reduce this to the following. In English we would see:

In German:

And in Japanese:

You can download the internationalised installation instructions shown in these screenshots from this page. In Apple’s words “When users launch a well-localized application, they should feel fully at home with it and not feel like it originated from some other country”. The same should be true of documentation (and, it follows, the install process of an application too). This idea helps to achieve this.

The future

It would be nice if Apple provided a framework for documentation that made internationalised documentation easier in the next OS X release. People would feel more secure if developers weren’t shipping small applications that open documentation, and instead shipped a bundle with just documentation (and plists) in it. I have some ideas Apple are welcome to if they are interested…

Internationalised Documentation in Mac OS X

One thought on “Internationalised Documentation in Mac OS X

Leave a Reply

Your email address will not be published. Required fields are marked *

To prove you're a person (not a spam script), type the security word shown in the picture. Click on the picture to hear an audio file of the word.
Anti-spam image