Archive for August, 2009

Code Based Localisation

Friday, August 14th, 2009

Code Based Localisation in xCode 3.0+ SDK

Code based localisation focuses on any strings you may have in your code. Finding these strings and making them dynamic. This is a contrast to how localisation is done in say Flash where the localisation methods are normally set up by the developer. Kind of like Flex.

If you are after NIB Localisation checkout this post here

Abstract:
A localised project needs a local specific folder that follows a name convention made up of 2 parts. First is the language like “English”, “French” or “Japanese”. The second is the local project abbreviation “.lproj” putting them together you get folders by the name “English.lproj”, “French.lproj” or “Japanese.lproj”. All the local based copy and assets will end up in the respective local folder. You can create these folders manually but I like to get xCode to create them using the localisation functionality built into the IDE.

Basically any text that is set via code needs to be set using NSLocalizedString this takes 2 strings. The first is the the copy that needs localisation. The second string it takes is the comment that appears above the name value pair.  see example:

Once you have written your code using NSLocalizedString with all the necessary default copy you will run a terminal script that will pull out the default strings strings to create a .strings file which you would then localise. “genstrings” is the command line tool used to interrogate your .m files to find what needs to be localised.

Once you have your localised .strings file you simply copy it to the different local folders updated the copy to the respective local and bobs  your uncle, its done.

Implementation:

  1. create a new project in xcode it should not matter what type but I will use an iPhone View-Based Application.
  2. add the bellow code to the viewControler of the newly created project to quickly add some uilabels
  3. Open the terminal window and navigate too the root of you project folder. This is the folder that contains your Classes folder.
  4. Run “genstrings ./Classes/*.m” in the terminal which will scan every .m file in your Classes folder for any references to NSLocalizedString and added them to a Localizable.strings file which should appear in the root of your project folder.
  5. In the finder navigate to the root of the project folder and then drag and drop Localizable.strings from the Finder to the resource folder in XCode remembering to insure that the “Copy items into…” check box is unchecked. Also make sure that Text Encoding is set to UTF-16 to insure all languages are covered.
  6. Finally press add.
  7. Right-Click the newly added Localizable.strings then select “Get Info”.
  8. Select the General tab from the “Get Info” panel
  9. Click “Make file Localizable”
  10. Click back on the general tab
  11. Click “Add Localization”
  12. Enter your new Locals “French”(from the English name section of the link) and or see here for full list: http://www.loc.gov/standards/iso639-2/php/English_list.php
  13. Once you have added the Locals for Localizable.strings close the “Get Info” window
  14. Run your app go to the settings panel>>Genral>>International change your local and it should display your localised text.

NIB Localisation

Friday, August 7th, 2009

NIB Localisation xCode 3.0+ SDK

There are 2 ways to localizes iPhone application and regular OSX applications. The first is localizing the NIB file. This automatically hard codes the localized copy into a NIB file. This works as of iPhone SDK 3.0 should work on previouse versions and future versions but that was my version at the time.

You can also localise with code but that is not the focus of this point check back for Code based localisation maybe next week.

Abstract:
A localised project needs a local specific folder that follows a name convention made up of 2 parts. First is the Language, like “English”, “French” or “Japanese”. The second is the local project abbreviation lproj. Putting them together you get “English.lproj”, “French.lproj” or “Japanese.lproj”. All the local based copy and assets will end up in the respective local folder. You can create these folders manually but I like to get xCode to create them using the localisation functionality built into the IDE.

NIB localisation works by taking a NIB that was built for one local with all the copy hard-coded into the NIB then scanning the NIB with the command line tool ibtool. Extracting the copy to a strings file. The strings file is then copied and localised for each local. Then another script hard codes the localised strings into the respective NIBs. This process only uses the generated strings files once to get the NIBs localised. Once this is done the Strings files are no longer necessary.

Implementation:

  1. create a new project in xCode it should not matter what type but I will use an iPhone View-Based Application.
  2. open up the view controller NIB in interface builder add some labels and buttons add some copy to them
  3. save and close interface builder
  4. in xCode right click the view controller NIB and click “Get Info”
  5. make sure you are in the genral tab then click “Make file Localizable”
  6. select the “General” tab again as may change after clicking “Make file Localizable”
  7. click “Add Localization”
  8. Enter your new Locals like “French” from the English name section of the link see here for full list: http://www.loc.gov/standards/iso639-2/php/English_list.php
  9. close “Get Info” Panel
  10. open up terminal
  11. navigate to your xCode project folder in terminal
    1. now we are going to run the command line script above to scan your nib file and generate a strings file below I have broken down the command so you can replace what u need
    2. I will use    ibtool –generate-strings-file NIBCopy.strings English.lpoj/LocalizationNIBViewController.xib
    3. ibtool is the command line tool called Interface builder tool that is installed by default when u install xCode
    4. –generate-strings-file   is the ibtool command that creates a strings file from a nib
    5. NIBCopy.strings is the name I  have chosen for my strings file u can  rename it if you want but maintain the .strings at the end
    6. English.lpoj/LocalizationNIBViewController.xib    is the path from the root of my xCode project folder to the NIB file i want to get scanned you must rename this to match the path and name of your NIB
    7. in your case you should only have to replace the NIB path from sub step 6
    8. so you should end up with something similar to ibtool –generate-strings-file NIBCopy.strings English.lpoj/LocalizationNIBViewController.xib
    9. it is likely that you will get the error “Unable to find either a loadable database or a Nodes.xml configuration file” i get it too don’t worry about it assuming your strings file was generated it will contain the name value pairs from the nib
    10. check to make sure your NIBCopy.strings is created if so move on else go back to sub step one and try again maybe type out the whole request manually in-case copy pasting messed it up a bit
  12. now copy the NIBCopy.strings to the French folder and any other locals folder you have created
  13. update and localise the NIBCopy.strings in the respective folders
  14. once again load up the terminal window
  15. navigate to the root of your project folder in the terminal
    1. now we are going to run the command line script above to take your NIBCopy.strings that contains your localised copy and hard code it into your localised NIBs
    2. ibtool is the command line tool called Interface builder tool that is installed by default when you install xCode
    3. –strings-file the ibtool command that refers to a strings file
    4. French.lproj/NIBCopy.strings my french localised strings file
    5. –write the command that writes a NIB file based on a Strings file and a NIB file
    6. French.lproj/LocalizationNIBViewController.xib the NIB file that will be writen/updated with the localised copy
    7. English.lproj/LocalizationNIBViewController.xibthe NIB file that will be the template for the localised french NIB file above
    8. it is likely that you will get the error “Unable to find either a loadable database or a Nodes.xml configuration file” i get it too don’t worry about it in fact that is how i know it worked 😉
    9. repeat sub step 1 to 7 for each localised NIB file local
  16. to test this either open up the localised NIB in interface builder or run the app and change the language settings in the simulator or on your developer iPhone
  17. the strings files are no longer needed as the copy is now hard-coded into the NIB