How To Localise Your Mac/iPhone app

Create a project

Create a user and define a project at App Translate

(at the moment, you need to email me to get permission to create projects)

Mark your localisable strings with the standard apple macro

NSLocalizedString(key,comment)

The translation helper uses genstrings to pull localisable strings out of your code. All strings defined with this macro (or any of the other standard macros in NSBundle.h) will create localizable string tables that the translation helper will use.

So for example

((DisplayCell *)cell).nameLabel.text =@"Credits;

becomes

((DisplayCell *)cell).nameLabel.text = NSLocalizedString(@"Credits",nil);

the translation helper will treat this as a key "Credits" with a corresponding text of "Credits"

(Optional) Manage long strings seperately

if you have a long string where you don't want the key and the text to be the same, then you can use the standard non-macro approach

NSString *longString = [[NSBundle mainBundle] localizedStringForKey:@"keyForLongText" value:@"" table:nil];

you will then have to manually add a string file in the 'GeneratedStrings' folder of your localisation folder (see details later).

This file can have any name and will contain the line

"keyForLongText" = "insert your long text here";

Connect to the App Translate service

Download the translation helper

Launch and enter your log in details

Click on the 'Setup' tab

Click Login / Update and you should now see your project(s).

Select the project you want to work on

Set up your project

click on the 'Files' tab

select your project directory (the base directory for your project)

select your localisation directory which should ideally be in your project directory (I use a folder called Localisation within my project directory)

add at least one of the files that you have adapted with NSLocalizedString macros to the 'Files for localisation' table. (you'll need to select them all eventually)

Generate String Tables

select the files that you want to work on in the table (they should show a blue or grey highlight)

click the 'Genstring' button.

This will generate a file in <localisation directory>/GeneratedStrings

The name of the file will be the path from your project directory to the file (just to help you see what is happening)

You can open this file in a text editor and see that the strings have been extracted

(Optional) Build additional String Tables

if you want any string tables that are not automatically generated, then just create them in the GeneratedStrings folder

Upload strings to web

Click upload and all strings from all string tables in the GeneratedStrings folder will be uploaded

once you have uploaded strings, you can update them by the same method.

• Make sure that you click login/update in the setup page so that the helper knows what strings exist already
• Click on upload, and the helper will modify any strings which have different values for a given key
• Note - you can only have one value for a key in the project as this system will ultimately use the single default Localizable.strings table

Get your users to do some translating!

Get some users to log in and provide translations. (you can use google's translation in the meantime for testing, so you can ignore this step!)

Then click on 'My Projects' and for each language, click on the link in 'Select default translations'

For each string, you'll need ot select a translation from the ones that your users have offered, or from google's translation.

Build the default localisation table

Click on Merge to Localizable.strings

This will generate a file called Localizable.strings in <localisation directory>/Resources/<default language code>.lproj

Drag that file (not the folder) to the resources section of your project

Magically get your translations

Click on 'Output translations'

This will generate a file for each language called Localizable.strings in <localisation directory>/Resources/<language code>.lproj

You now have to go in to each of these folders and drag the file to the same place as the Localizable.strings in the resource section of your project (don't drag the folder, and don't drag the file on to the Localizable.strings)

You should now see in your resources section an item called Localizable.strings which opens up to show the languages

(If anyone can figure out way to drag the folders, rather than having to drag each file seperately - please let me know!)

Build and Go

That's it - you are localised!

 

More Info...

Xib / Nib files

The translate helper can handle xib and nib files by using ibtool to extract strings and reinsert them.

You'll need to put your Xib file in an en.lproj folder (or whatever your base language is) in order to let xcode recognise it as localizable. I tend to use

Localisation/English.lproj/xibFile.xib

then your language resource will end up in

<localisationFolder>/Resources/Localisation/English.lproj/<newLang>.lproj/xibFile.xib

in the same place, you'll find the translated string file xibFile.xib.strings. You can ignore this file.

The main problem with localising xib files this way is that the generated keys are not helpful, and have a high probablilty of clashing if you have multiple xib files.

Until I make a better way of handling these, the best approach will be to set any text in your xib file from your code.

Format Strings

If you have strings with format placeholders in them ( @"the name of your file is :%@" ), then you'll need to watch these carefully. Google will translate them wrongly, and you'll need to cueck user translations.