You are currently looking at an older section of the website.
Please check the new version of the site at for updated content.

wincent knowledge base

« Cleaner HTML using CSS | Main | Costs of running a software small business »

November 11, 2004

Localization on Mac OS X

Mac OS X has a fully-fledged and elegant localization infrastructure that enables software to be translated into multiple languages and shipped as a single convenient package to end users. In this article I don't rehash the material on localization that is already available on the web. I am specifically writing about what you would need to do to produce a localization of a Wincent product.


This article assumes some prior knowledge, so if you don't yet know about the following topics you should probably do some background reading and make sure you have the appropriate tools first:

Localization procedure for Wincent software

Whenever I prepare a final build for shipping, as a final step in the build process I use a collection of tools, including Apple's genstrings and nibtool utilities, nibtrans by Manfred Schwind and a modified version of stringsUtil by the OmniGroup, to produce a localization package that is made available for download on the corresponding product's download page.

Before you start work on a localization you should contact me to let me know that you are going to start work on it. Sometimes more than one person steps forward to do a localization, so it's useful to coordinate your efforts with other people and minimize duplication of effort.

By default, every localization pack includes one or more English localizable project folders ("English.lproj" or "en.lproj") containing the unlocalized, English-language versions of the program resources. Sometimes there is more than one such folder because a given product may actually be comprised of various components, each with its own "English.lproj" or "en.lproj" folder. If you are localizing a product into a target language for the first time, make a copy of the English resources, rename the containing folders appropriately (for example, "Spanish.lproj", "Japanese.lproj" and so on), and perform the localization. You must localize every file in every component otherwise the localization will be incomplete.

In cases where a localization already exists for a given product, the build process will merge the new, unlocalized portions of the project into the existing localized resources. In this way you don't have to begin the localization process all over again from the beginning. Rather, you can do an incremental localization, translating only the new (unlocalized) additions. Where pre-existing localizations exist, the merged lproj folders awaiting incremental localization will be included in the downloadable localization pack. Look at each and every file and make sure that there are no new strings that need to be translated. When you send back the updated localization you should only send files to which you actually made changes; if you did not make any changes to a file then do not send it back (the easiest way to do this is probably to simply delete those files to which you did not make any changes). Likewise, if you updated the Japanese localization do not send back the other localizations as well.

As a general rule localization packs contain string files and not nib files; this is to streamline the process and make incremental localization more straightforward. It is also necessary in some cases where the nib files depend on private frameworks which are not included in the standard Mac OS X install and which Interface Builder will refuse to open. It is important that when you provide translations that you pick wordings that are of approximately the same length as their untranslated counterparts. If the translations are too lengthy then they will not fit within the geometry of the user interface. I can make minor adjustments to the interface geometry, but in general it is best for the purposes of consistency if translations can be chosen which obviate the need to do this.

If you do decide to do a localization please make sure that it is complete. Merging localizations is a time-consuming process that takes a lot of work, so it is not very efficient to integrate partial localizations (and then updates to those localizations). This is why I ask that when you do an updated localization that you only send back the files which you have actually modified. If you do not have the time to do a full localization of every localizable file then you should not go ahead with the project. Fully localizing the project also means localizing the InfoPlist.strings files which are often overlooked; for example, the English words for "copyright" and "version" should be translated.


  • Use a Unicode-aware text editor, such as ADViewer.
  • Save ".strings" files with UTF-16 encoding, as per the Apple documentation.
  • Save ".plist" files with UTF-8 encoding, as per the encoding attribute at the head of the file.
  • Double check the encoding before you send back the localized files.
  • Keep your translations roughly the same length as the original text.
  • If you can, get a friend to double-check your translations.
  • Localize all the files, including InfoPlist.strings files.
  • Only submit complete localizations, not partial ones.
  • If updating an existing localization, only send back the files which you actually modified.
  • Send only the lproj folders for the specific language you are working on; do not send back the lproj folders for the other languages.

Posted by wincent at November 11, 2004 02:08 AM