Standards for comments in NSLocalizedString

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).