Developer: localization

Archipel now fully supports Cocoa-like localization. So if you want to help us to translate Archipel, please read this page.

Prerequisites

We use Apple's tools ibtool and genstrings that are provided with XCode. So you (sadly) need a Mac with Mac OS X and XCode 4 installed.

BUT, you only need Mac OS to extract and inject the localization files. You can translate without needed anything more than a basic text editor.

A little documentation

To understand how the localization work with Cocoa apps, you can read this document.

Prepare an Archipel bundle to be localizable

This is only required for module that have no support for localization yet, or for your own module. If you just want to translate an existing module into a new language, please skip this section.

Not localization ready module

If the bundle has not be modified to be localizable, you must do the following to initialize the translation support:

• Go to /ArchipelClient/ModulesSources/MyModule/Resources
• Create a new folder named en.lproj
• Create a new folder named fr.lproj
• Create as much as locale folder you need
• Copy the /ArchipelClient/ModulesSources/MyModule/Resources/MyModule.cib into each xx.lproj
• Remove the Resources/*.[xib|cib]

Then, you need to declare a new function in each module's files that will use localization. For example, let's say that our module has two classes in two separate files (if you have more than one class in one file, you are doing bad).

Then add at the bottom of the file :

// add this code to make the CPLocalizedString looking at
// the current bundle.
function CPBundleLocalizedString(key, comment)
{
    return CPLocalizedStringFromTableInBundle(key, nil, [CPBundle bundleForClass:TNMyModuleController], comment);
}

Make sure you replace TNMyModuleController with the name of the class in the file.

Then for each localizable string, use this function. For example, if we have:

[...]
[fieldPreferencesAutoRefresh setToolTip:@"Hello world"];
[...]

Then replace it with :

[...]
[fieldPreferencesAutoRefresh setToolTip:CPBundleLocalizedString(@"Hello world", @"Hello world")];
[...]

You can use this TextMate snippet to make your life easier.

When you are done, you need to generate the strings file. And as we are cool guy we have added a tool in ArchipelClient root directory name localize that will do all the work for you (extract, inject if needed, and merge strings file). You can run this tool right from buildArchipel:

cd /ArchipelClient/
./buildArchipel -l --modules=MyModule

Ignore eventual warnings. Then at the end of the script, you will have some new files in xx.lproj folders:

/ArchipelClient/ModulesSources/MyModule/xx.lproj/MyModule.strings
/ArchipelClient/ModulesSources/MyModule/xx.lproj/Localizable.strings
/ArchipelClient/ModulesSources/MyModule/xx.lproj/Localizable.xstrings 

You can notice that the MyModule.strings contains all the label in your ```xib`` file and Localizable.strings all the localizable string (i.e. one that are passed to CPBundleLocalizedString)

Already localization ready module

If you can already find en.lproj in the module's Resources directory, then the module is already localizable. In this case, just duplicate the en.lproj module into, for instance, es.lproj and continue reading.

In any case

Now you can work with the strings files (ignore the xstrings. this one is needed by Cappuccino, but you will never have to edit it manually)

Translate

Now, open the strings files and do the real translation work.

[...]
/* Display the file column in the log table */
"Display the file column in the log table" = "Affiche la colonne Fichier dans le tableau de log";

/* Display the method column in the log table */
"Display the method column in the log table" = "Affiche la colonne Méthode dans le tableau de log";
[...]

Reinject the changes

Changes in CIBNAME.strings must be reinjected in the cib file. To do this, simply rerun :

./buildArchipel -l --modules=MyModule

Tips

• ALWAYS use en.lproj/MyModule.xib as base. It is considered as the main XIB by localize
• You can use xcodecapp-cocoa to update in live your change (i.e. translate xibs to cib)