Custom localization system for your iphone games

__________

Localizating your application is crucial if you want to reach a broader audience, imaging how a Spanish or German kid will react if the game they try to play is in english or french, they just won't buy your game.

The iphone SDK has it's own localization system, which works very well, but as you may know the default localization system does not allow you to change the language in run-time, just use the OS default system, and it also does not allow other languages beyond what's defined on the iphone OS. So, if you want to change the language from a menu in your game there are many things you can do:

• write your own system, which is utterly boring and implies parsing your language files, or...
  
• overload and use what the framework has to offer.

This post tries to explain, first, how to the new localization system works, and second how to add localization to your system and how to use it to change the language in run-time.

Note: Although it is used for games it might be used for your own applications as well.

How the new system works

a. The iphone SDK way

The iphone SDK provides the NSLocalizableString("tag", "alternative") macro to obtain the localized string, from the Localizable.strings, for the given "tag" string or in case it didn't find a proper match it returns the "alternative" string.

I'll explain in the Implementation section how to build the Localizable.strings, just know that it has a strings in the format:

"tag" = "Localized text for the tag";

E.g.

NSString *localizedStr = NSLocalizableString(@"hello", @"Hello World");
//IF it finds the "hello" tag on the localizable.strings for the current OS language it will return the localized string.
//ELSE will return "Hello World"

b. The new way

With adding the LocalizationSystem.h and LcalizationSystem.m you add the following functionality to the default system.

• you'll be fully compatible with what was already done.
• you'll be able to change the language in run-time
• you'll be able to support languages not added in the iphone OS implementation, like Esperanto, Catalá, Elfic,...

Using it:

It's usage is fairly simple, there has been defined 4 macros that extends the default functionality. These macros are:

1. LocalizationSetLanguage("language")
Using the following macro you'll be able to change the localization default language into the language you want.

// Sets the desired language of the ones you have.
// example calls:
// LocalizationSetLanguage(@"Italian");
// LocalizationSetLanguage(@"German");
// LocalizationSetLanguage(@"Spanish");
//
// If this function is not called it will use the default OS language.
// If the language does not exists y returns the default OS language.
- (void) setLanguage:(NSString*) l{
 NSLog(@"preferredLang: %@", l);

 NSString *path = [[ NSBundle mainBundle ] pathForResource:l ofType:@"lproj" ];

 if (path == nil)
       //in case the language does not exists
       [self resetLocalization];
 else
       bundle = [[NSBundle bundleWithPath:path] retain];
}

The "language" string should match what you have on you Localizable.strings file

2. AMLocalizedString("tag", "alternative")
Gets the Localized string:

// Gets the current localized string as in NSLocalizedString.
//
// example calls:
// AMLocalizedString(@"Text to localize",@"Alternative text, in case hte other is not find");
- (NSString *)localizedStringForKey:(NSString *)key value:(NSString *)comment
{
 return [bundle localizedStringForKey:key value:comment table:nil];
}

The AMLocalizedString works just the same way as the NSLocalizedString.

3. LocalizationReset;
Resets all settings, in case you'll allow your user to leave the language settings as default.

// Resets the localization system, so it uses the OS default language.
//
// example call:
// LocalizationReset;
- (void) resetLocalization
{
 bundle = [NSBundle mainBundle];
}

4. LocalizationGetLanguage;
Gets the current set language.

// Just gets the current setted up language.
// returns "es","fr",...
//
// example call:
// NSString * currentL = LocalizationGetLanguage;
- (NSString*) getLanguage{

 NSArray* languages = [[NSUserDefaults standardUserDefaults] objectForKey:@"AppleLanguages"];

 NSString *preferredLang = [languages objectAtIndex:0];

 return preferredLang;
}

Implementation

Step 1. Creating the project

I'll use a Cocos2d 0.99.0 project as I wanted to demonstrate the system on games, but you'll be able to create the project better suits your application.

Step 2. Add localization to your project

To do so, you'll need to:

1. in resources group within your project, right click add... -> New File
2. I'll appear a window like the following. Go to Mac OS X -> Resources and select Strings File. Name your file "Localizable.string".
   

At this point you have added the localization file to you project, now open the information of the file (right click -> Get Info / cmd + i), and on the General tab press the Make File Localizable. You will get this as a result.

Now its time to add the localization you want.
tip: Name it as the language name in english. e.g "spanish", "french", "german",...

Step 3. Add the text.

Now open each of the files to add the text you want to localize, remember the format. Do it in the desired language file.

"tag" = "localized text";

"hello" = "HOLA MUNDO";

Add this point is exactly as if you were adding normal localization.

Step 4. Add the new localizatio file to your project.

You have to add the LocalizationSystem.h and LocalizationSystem.m to your project.

This can be done in two ways.

1. Right click -> Add existing files... wherever you want to add the files, select them and click ok.
2. You can darg from the sample project the group containing both files to your project.
   

Step 5. Just use the library.

1. Add

#import "LocalizationSystem.h"

In the classes that need localization,

2. Use AMLocalizableString instead of NSLocalizableString.

3. Use LocalizationSetLanguage to change the language.

LocalizationSetLanguage(@"Spanish");
CCLabel* label = [CCLabel labelWithString:AMLocalizedString(@"hello",@"Hello World") fontName:@"Marker Felt" fontSize:32];

The label will contain "Hola mundo".

Download

You can download a sample project with everything on it.
It consist of a clean project, just to be as familiar as possible, with the library added.

that will run as:

Each button represents a language added and OS, returns to the OS default language.

The files:
LocalizationSystem.h
LocalizationSystem.m

The sample project
Test project

If anyone has any suggestion or question leave it in the comments. I'll be glad to answer.
Thank you for reading.