Introduction

The second parameter of NSLocalizedString is the translator comment. It does not affect the key lookup at runtime, but it matters during localization because it gives humans context about what the string means. In practice, that comment is documentation for translators and for future developers who need to understand why a particular phrase exists.

The Basic Shape of NSLocalizedString

In Swift, the common form looks like this:

let title = NSLocalizedString("settings.title", comment: "Title shown at the top of the settings screen")

The first argument is the lookup key, and the second argument is the comment. In Objective-C, the idea is the same.

NSString *title = NSLocalizedString(@"settings.title", @"Title shown at the top of the settings screen");

At runtime, the localization system uses the key to find the translated value in the appropriate .strings file. The comment is there to help people, not the lookup mechanism.

Why the Comment Matters

Many English strings are ambiguous out of context. A word such as "Open" could mean "unlock," "launch a file," or "operate now." Translators need to know which meaning applies.

A good comment explains the role of the string in the interface. For example:

1let buttonLabel = NSLocalizedString(
2    "document.open",
3    comment: "Button label that opens the selected document"
4)

That gives a translator enough context to choose the correct verb in another language.

Without the comment, a translator may guess wrong, especially when the key itself is short or abstract.

The Comment Is Not User-Facing Text

A common misconception is that the second parameter appears in the app or is used as a fallback value. It does not. The comment is not displayed to end users.

If you want a fallback string for a missing localization, that is a different API pattern. NSLocalizedString's second parameter is purely descriptive metadata.

That is why empty comments compile and run, but they reduce translation quality. The app may still function, yet the localization process becomes harder for the humans involved.

What Good Comments Look Like

A useful localization comment should answer one or more of these questions:

• where is this string shown
• what action or concept does it represent
• who is it addressing
• is the tone formal, neutral, or casual

Examples:

let cancel = NSLocalizedString("common.cancel", comment: "Button that closes the current dialog without saving")
let quota = NSLocalizedString("storage.quota.full", comment: "Warning shown when the user has no remaining cloud storage")

Those comments are short, but they give context that a raw key alone often cannot.

Keep Keys Stable, Improve Comments Freely

The key is part of the lookup contract, so changing it can affect your .strings files and localization workflow. Comments are different. You can usually improve them over time without changing runtime behavior.

That makes comments a cheap place to improve localization quality. If a translator asks for clarification, updating the comment is often the correct response.

It also means keys and comments should serve different purposes. The key should be stable and predictable. The comment should be descriptive and useful.

Common Pitfalls

The most common mistake is leaving the comment empty for every string. That saves a few seconds during development but pushes ambiguity onto translators and reviewers later.

Another mistake is writing comments that simply repeat the key or visible English text. A comment like "Settings title" is often weaker than "Title at the top of the account settings screen," because the latter gives actual UI context.

Developers also sometimes confuse the key and the source string. Some teams use the visible English text as the key, while others use structured keys such as settings.title. Either approach can work, but the role of the second parameter stays the same: it is contextual metadata.

Finally, do not put secrets, internal jokes, or unstable implementation details in localization comments. Comments often travel through translation tooling and should remain professional and helpful.

Summary

• The second parameter of NSLocalizedString is a comment for translators and maintainers.
• It does not affect runtime lookup or appear in the UI.
• Good comments explain context, meaning, and usage of the localized string.
• Empty comments are allowed, but they reduce translation quality.
• Keep keys stable and use comments to improve clarity for localization work.