Localization

From Quicksilver Wiki
Jump to: navigation, search

Localising Quicksilver[edit]

In order to help localise Quicksilver, visit the Quicksilver Transifex Project page. All files that are currently localisable are shown on Transifex.

Thank you for helping!

Localisation for Developers[edit]

Localising Strings in the code[edit]

For developers only:

All strings that are eventually visible to the user should be localised, excluding NSLog strings (discussion needed). Note that NO strings other than English strings should be translated downstream of the Transifex project. The workflow is to push only English files and pull all other translations from Transifex.

If you are working on the core App using the NSLocalizedString(@"my english string",nil) method. There is no need to create a corresponding entry in any .strings file, as if none exists, the original string will be used.

In order to localise plugins, you should use the NSLocalizedStringFromTableInBundle(@"Error renaming File: %@ to %@", nil, [NSBundle bundleForClass:[self class]], nil).

In both the above cases, nil was passed as the last argument. This is a 'comment' entry. See Apple's documentation.

Passing nil as the table (as has been done in the above two cases), the default 'Localizable' table (or Localizable.strings file) is used for storing and subsequently translating the string. Use

NSString *NSLocalizedStringFromTable(NSString *key,
   NSString *tableName,
   NSString *comment)

if you want to set the table for the main bundle (that is, the core App), or set the table string in

NSString *NSLocalizedStringFromTableInBundle(NSString *key,
   NSString *tableName,
   NSBundle *bundle,
   NSString *comment)

for a plugin.


As has previously been stated. There should be no need to create an English string in the .strings file, as by default the NSLocalizedString… methods return the input string if nothing is find. Secondly, we use genstrings to do all the heavy lifting for us anyway.

Genstrings[edit]

This will be implemented as a build phase in the Quicksilver project. It will output all the required .strings files ready for submission to Transifex

Pushing and Pulling from Transifex[edit]

First you must install the Transifext Client and set up your ~/.transifexrc file with the correct username and password. Here's an example:

[https://www.transifex.com]
hostname = https://www.transifex.com
password =
token = 
username =

If you have privileges to access the Quicksilver Transifex project, you should know the username and password.

With this set up, in the root directory of the Quicksilver project, run tx status to see the status of the Transifex project. See the Transifex Client page (above) on commands on how to add new .strings file to the project, and deal with common tasks.

The two main tasks that should be known are:

tx push -s which pushes all the source (-s) files to the server. I.e. all the English files. NB: The default language for all strings is en_US (not just en) when pushing to Transifex, meaning en_GB strings could be created at a later date. This means all strings should be in en_US form (e.g. "Color" and not "Colour")

tx pull -a --minimum-perc=80 -f This command pulls all translated files within a minimum completion percentage of 80%. Note we use 80% instead of 100% as there are often cases where strings are left blank since they are the same as the original translation. This is a rather arbitrary number but appears to work relatively well in practice. -f forces Transifex to pull updated files and not just new files.

The -a flag pull all files from Transifex, including English files (there's currently no way to only pull translated files) so ensure that your local English .strings files are either pushed to the Transifex server or checked in with git

With the new files in place, you can use git's git status to view what files have been modified/added. If any files have been added, they also need adding to the .xcodeproj. This should be done manually and not automated (according to the Growl Team). The process of adding files to the .xcodeproj is yet to be tested, but it should just be a matter of ticking the appropriate localisation for the corresponding .strings file

Adding new languages to Xcode[edit]

If you are adding an entirely new language to Quicksilver, before doing a tx pull, always add the language in Xcode first (found by clicking the 'Quicksilver' project, then under the 'Info' section of the project).

Dealing with difficult files[edit]

Quicksilver uses many different plist formats for getting information. One example is DefaultsMap.plist. For these 'awkward' files, always do a diff between the English and localised files, to make sure strings that shouldn't be translated have been left. An example of strings that should be left as they are in DefaultsMap.plist are those referring to a User Default key of some sort.