How does incremental localization work?

Question

I'm trying to build my first localized application. I have all the strings in code translated using NSLocalizedString (for use with genstrings tool). Now I'm bumping into ibtool. How does incremental localization work? Regarding to the manual page, I should write something like this:

$ ibtool --previous-file path/to/prev.xib \
--incremental-file path/to/inc.xib --localize-incremental \
--write path/to/new.xib mod.xib

Where do I get the incremental file? To my understanding if I'm using the version control (git/svn), the "old" file is at few commits ago, the incremental file is the diff and path/to/new.xib is newly produced xib file. mod.nib is a mystery to me. Can anyone explain me how this works? Also - how do I start the localization of a xib if no previous versions are available (i.e. doing not incremental, but initial localization)?

Answer 1

I think their choice of terminology, particularly for --incremental-file, is causing confusion. The idea is that you have an old version of your xib in two languages (source and target) and that you have since changed it in your source-language and want to update the target-language version to match.

Let's take an example. You previously had home.xib in English (source language) and got someone to translate it to French (target language). You've since developed a new feature and you now have an updated version of home.xib in English in which you added a UILabel and a UITextField and moved things around. The command you showed can help you get an updated version of home.xib in French so that it has the new UILabel and UITextField and that things are moved around like in English. Note that any textual content that you set in your new UILabel and UITextField will be added in English and will then need to be translated in the French xib (but you can automate this by adding --import-strings-file and providing the translations in one more file).

So if we map the command you showed to this example:

• --previous-file path/to/prev.xib specifies the old English xib
• --incremental-file path/to/inc.xib specifies the old French xib
• --write path/to/new.xib specifies the new French xib that will be created
• mod.xib specifies the new English xib

For your other question regarding how you start the process, really it depends how you will localize your xibs. You'll obviously create the new language versions of the xibs (in XCode, you just add a language to the language list of the xib and the localized xibs are created automatically). And then if you localize them in Interface Builder yourself, then you'll simply make the relevant changes (translation of text and any necessary resizing) in the localized xibs. Or you could extract the text in the xibs into .strings files, get them translated, and inject them into the relevant language version of these xibs. For this, again you will use ibtool but with --generate-strings-file for the extract phase and with --import-strings-file for the inject phase.

Answer 2

I wrote a script for git projects which automates the steps necessary (as described in the answer above) to migrate a change to a different language.

Usage:

migrate_changes.sh <target_language> <xib file without ending>

Example:

After you've committed your changes to the english xib file, run the script at the root of your resource folder.

migrate_changes.sh de MyViewController

Source:

#!/bin/sh

LANG_FROM='en'
LANG_TO=$1
XIB_FILE=$2

FROM_FILE=${LANG_FROM}.lproj/${XIB_FILE}.xib
PREV_FILE=${LANG_FROM}.lproj/${XIB_FILE}_old.xib
TO_FILE=${LANG_TO}.lproj/${XIB_FILE}.xib

# checkout old version of xib file
git show `git log -2 --format="%H" $FROM_FILE | tail -n 1`:./$FROM_FILE > $PREV_FILE

# merge changes
ibtool --previous-file $PREV_FILE --incremental-file $TO_FILE --localize-incremental --write $TO_FILE $FROM_FILE

# remove previous version
rm $PREV_FILE