shinywhitebox docs
There have been a number of changes in the way shinywhitebox products handle localization. We have implemented new code to dynamically replace localized strings in user interface NIBs, thus alleviating the need to maintain multiple copies of the same NIB while also greatly simplifying the job of the localizer. We have also refined our interaction with localizers; how they receive localization-ready applications and how we save their changes back to our source repository.
In this tutorial we will retrieve a localization-ready application from the shinywhitebox website, describe our changes to the basic localization process using iLocalize, and describe the output format of the final localized application. We will create an iLocalize project from scratch to create localizations conforming to the new process. We are going to use Stomp as an example and we are going to localize for the German language.
But before we get started, here's a quick list of "do's" and "dont's":
- Do: please send us the iLocalize dictionary for the language your localized after you've completed translation. We like to keep our application resources in a centralized, and redundant source repository.
- Do: please send us localized applications containing only the language for which you are localizing.
- Don't: localize NIBs, it's not necessary and we ignore them. We only use "strings" files. Strings in NIBs are dynamically replaced on the fly.
- Do: double-check the user interface to ensure it still looks correct and report any inconsistencies to us.
- Do: always get the latest version from us before beginning localization.
- Do: rebuild missing "strings" resources from the base-language, if necessary.
- Don't: rebuild missing NIB files, they will be ignored when we integrate your changes into our source repository.
Let's get started!
First, we are only localizing the strings files that exist in the application bundle, so we need not be concerned with where we get the application from. For example, as long as we know we are using the latest version of Stomp, we can be sure that we have the most up-to-date localizations for our target language (if our target language already exists, that is). We need not worry if the NIB files are compressed since we will not be localizing them. This is the first major change to how our new process works: NIB files do not need to be localized but the application still should be reviewed. When importing the changes we get back from localizers, we ignore any localized NIBs. We've developed a cool system (with the help of some sample code from Wil Shipley) where we always load the English user interface, then search our bundle for a strings file of the same name as the NIB we're loading and of the same locale our computer is in. If we find a strings file, we replace all the English strings in the NIB with the localized versions found in the strings file. In this way, we only need to maintain one NIB for any language. This also means that as a localizer, you only need to translate the strings files in the bundle. When testing the localized application in iLocalize, the application will run as if you had actually localized the NIB files. This saves time in that you no longer need to worry about localizing NIBs.
The latest application (in this case Stomp) can be downloaded directly from our website by navigating to the application's product page as shown here:
Once the latest application has been downloaded, the next step is to create a new iLocalize project for it. Even though this should be familiar to most localizers who have worked with iLocalize before, pay particular attention to this new process as it will make it easier for we, the developers, and you the localizer.
Create a new project for Stomp:
Click "Next" and be mindful of warnings, of course, but these are harmless in this case:
Select the language the you will be localizing here, if it exists:
After selecting the target language in the main iLocalize window, iLocalize may complain about some missing files for the target language. Some of these files we as developers ignore (e.g. Info.plist for some sub-component of the application bundle that is most likely empty) during our localized application import process. Indeed, localized versions of them may never exist in the application that localizers (or users for that matter) download from our website. Other missing files may be additional NIBs that have been added to the product for which strings files have been generated for English, but have not yet been localized (e.g. new features). The upshot of all this is that, to be on the safe side, select all the files marked as missing in the target language and select "Rebuild Selected Files from English" from iLocalize's "Project" menu.
At this point, you can go through and localize the application for the target language as you normally would, with the exception that you do not need to localize NIBs, only Strings files. Once the localization process has been completed and you've approved the changes and saved the project, the final step before exporting the application is to test it in the target locale. This is extremely important to us since though we try to ensure that there is enough space in the layout of the NIBs to accommodate all the various localizations, sometimes we miss potential issues and we very much appreciate additional input on items we may have missed!
Once testing is complete, the project can be exported for the target language(s). It is important (and it makes our job much easier) if you only export for the target language, even though the original application bundle that was downloaded most likely contained multiple localizations. If you only imported the target language, then you should only see one other language here besides English.
As you can see from the screenshot above, you will most likely get warning and/or error icons. This is most likely due to ignoring the NIBs, but it is always a good idea to double-check and make sure that nothing was missed.
Once the application is exported, you can archive it and send it to us. We will import the new or updated localization and new release of our products will contain the localizations.
Thank you!!