Standards for comments in NSLocalizedString - objective-c

Question

How do people write their comments for their NSLocalizedStrings? Is there a standard guideline that we should follow? For example if I have:
NSLocalizedString(#"Tap your account to sign in", #"");
and my comment is "Text that asks user to sign in by tapping on the account", is this a bit ambigous? Should I leave the comment out if it's pretty much self-explanatory?
Another question is, what if I have a bunch of ProgressHUD that has a text set to LoggingIn, what would be an easy way to sync across my app project that this needs to be localized into NSLocalizedString (#"Logging In", #"some description"); Is there a tool for performing such tasks?

Answer 1

The second parameter is a comment that will automatically appear in the strings file if you use the genstrings command-line utility, which can create the strings file for you by scanning your source code.
The comment is useful for your localizers. For example:
NSLocalizedString(#"Save",#"Title of the Save button in the theme saving dialog");
When you run genstrings, this will produce an entry in the Localizable.strings file like this:
/* Title of the Save button in the theme saving dialog */
"Save" = "Save";
In your specific example, it's fairly obvious what the comment means, but not the context. You should probably add some context like so:
NSLocalizedString(#"Tap your account to sign in", #"Instruct user to tap their account to sign in (Facebook account, main game preferences)");
That way the localizer knows exactly what button you're referring to.
This becomes even more important for buttons labelled "Share" or some other non-specific label:
NSLocalizedString(#"Share", #"Label for sharing button on main image editing screen");
(This is a modified version of my answer to this similar question).

Answer 2

Rob Keniger is right. I also would like to add this:
Second param can be used as .. default value!!
(NSLocalizedStringWithDefaultValue does not work properly with genstring, that's why I proposed this solution)
Here is my Custom implementation that use NSLocalizedString that use comment as default value:
1 . In your pre compiled header (.pch file) , redefine the 'NSLocalizedString' macro:
// cutom NSLocalizedString that use macro comment as default value
#import "LocalizationHandlerUtil.h"
#undef NSLocalizedString
#define NSLocalizedString(key,_comment) [[LocalizationHandlerUtil singleton] localizedString:key comment:_comment]
2. create a class to implement the localization handler
#import "LocalizationHandlerUtil.h"
#implementation LocalizationHandlerUtil
static LocalizationHandlerUtil * singleton = nil;
+ (LocalizationHandlerUtil *)singleton
{
return singleton;
}
__attribute__((constructor))
static void staticInit_singleton()
{
singleton = [[LocalizationHandlerUtil alloc] init];
}
- (NSString *)localizedString:(NSString *)key comment:(NSString *)comment
{
// default localized string loading
NSString * localizedString = [[NSBundle mainBundle] localizedStringForKey:key value:key table:nil];
// if (value == key) and comment is not nil -> returns comment
if([localizedString isEqualToString:key] && comment !=nil)
return comment;
return localizedString;
}
#end
3. Use it!
Make sure you add a Run script in your App Build Phases so you Localizable.strings file will be updated at each build, i.e., new localized string will be added in your Localized.strings file:
My build phase Script is a shell script:
Shell: /bin/sh
Shell script content: find . -name \*.m | xargs genstrings -o MyClassesFolder
So when you add this new line in your code:
self.title = NSLocalizedString(#"view_settings_title", #"Settings");
Then perform a build, your ./Localizable.scripts file will contain this new line:
/* Settings */
"view_settings_title" = "view_settings_title";
And since key == value for 'view_settings_title', the custom LocalizedStringHandler will returns the comment, i.e. 'Settings"
Voilà :-)