Notes For Localizers

Localizing Strings Files

Strings files generated by genstrings have content that looks like this:

/* Comment */

"key" = "key";

That is, the value string is the same as the key string.

Translators should type the localized version of the key string in place of the second string. Use the comment, if necessary, to understand the context in which the string is displayed to the user:

/* Comment */

"key" = "French version of the key";

If a string contains multiple variable arguments, you can change the order of the arguments by using the “$” modifier plus the argument number

/* Message in alert panel when something fails */

"Oh %@! %@ failed!" = "%2$@ blah blah, %1$@ oh!";

Just as in C, some characters must be prefixed with a backslash to be included in the string properly. These characters include double-quote, backslash, and carriage return. You can also specify carriage returns with “\n”:

"File \"%@\" cannot be opened" = " ... ";

"Type \"OK\" when done" = " ... ";

Strings can include arbitrary Unicode characters with “\U” followed by up to four hexadecimal digits denoting the Unicode character; for instance, space, which is hexadecimal 20, is represented as “\U0020”. This option is useful if strings must include Unicode characters which cannot be typed for some reason.

Strings files are best saved in Unicode format. This allows them to be encoding-independent, and simplifies the encoding to use when an application loads strings files. The TextEdit application can save in Unicode format. The encoding can be selected either from the Save panel, or as a general preference in TextEdit's Preferences panel.

For more information about modifying strings files, see “String Resources” in Resource Programming Guide.

Nib Files and ibtool

The term nib files used throughout this document describes an Interface Builder file in a generic manner. This description of Interface Builder files came from the .nib file extension used with the original implementation of Interface Builder. In OS X and iOS app projects, you will encounter Interface Builder files with extensions .nib, .xib and .storyboard.

• The original format uses files with extension .nib. This a proprietary, binary format for the representation of Interface Builder user interface objects and connections. When building an app, these files are copied directly into the app's bundle and loaded at runtime as required to supply the user interface.

• Starting with OS X v10.5 and Xcode 3, a new Interface Builder file format was created with the filename extension .xib. These files are a plain text XML representation of the Interface Builder user interface objects and connections. The advantage to this format is that it allows for plain text tools (such as diff, grep, and others) to be used for code analysis and version management in the development process. These files are processed to a binary form and inserted into the app’s bundle when a build is performed.

• With the introduction of iOS 5 and Xcode 4.2, another new Interface Builder file format has been introduced with the filename extension .storyboard. The .storyboard file is similar to the .xib file in design. It is a customized, plain text XML representation of the Interface Builder user interface objects and connections created when the storyboard interface design option has been chosen in creating an app project. The use of Interface Builder storyboards is the preferred design methodology for iOS app user interfaces.

The XML format of .xib and .storyboard files is highly customized for Interface Builder. You should not use plain text editors or generic XML tools to modify these files directly. Xcode 4.2 and Interface Builder can be used to edit all three types of nib files.

The command line tool for investigating and manipulating nib file contents, including strings file extraction and replacement, is ibtool. It performs the same functions for all .nib, .xib, and .storyboard files described by this guide. More information about the capabilities of ibtool beyond the localization procedures treated here can be obtained from the command line man pages.

Localizing Nib Files

You use Interface Builder to create nib files, and you should use Interface Builder to localize nib files. Typically you open all of the nib files in a language.lproj directory, localize all the strings, change the sizes of UI elements if necessary, and save the nib files. There are a few things to watch out for:

• Objects in a nib file typically have connections between them that should not be broken. Make sure you lock all connections before handing your nibs off to translation. For information on how to lock down your nib file, see “Localization” in Interface Builder User Guide.

• Panels and windows usually have minimum or maximum sizes that are specified through the inspector panel. If you must make a panel or window wider for a given language, it's likely that the minimum size also needs to be modified.

• Some UI objects support “tool tips” – little blurbs that come up when the user hovers on the UI element for a short while. You enter these strings in the inspector, where they should also be localized.