Introduction

The second parameter of NSLocalizedString is the translator comment, provided using the comment label in Swift. It is not displayed to end users at runtime. Its purpose is to give localization context so translators can choose accurate wording.

Basic Signature and Intent

Typical Swift usage:

1let title = NSLocalizedString(
2    "profile.header",
3    comment: "Header shown above account details on profile screen"
4)

• First argument: localization key.
• Second argument: context comment for translators.

This comment is metadata for localization workflow, not user interface text.

Why Comments Improve Translation Quality

Many UI strings are ambiguous without context. A short note prevents mistranslation.

Examples of ambiguous strings:

• Open can be a verb or adjective.
• Save can mean persist a file or reduce cost.

Contextual comment example:

1NSLocalizedString(
2    "action.open",
3    comment: "Verb on button that opens a selected document"
4)

Clear notes reduce translation churn and review cycles.

Advanced Variant with Table and Bundle

Foundation also provides a more detailed API:

1let text = NSLocalizedString(
2    "settings.title",
3    tableName: "Settings",
4    bundle: .main,
5    value: "Settings",
6    comment: "Navigation title for settings screen"
7)

In this variant:

• tableName selects localization table.
• bundle selects resource bundle.
• value is fallback text.
• comment still provides translator context.

This is useful in modular apps and frameworks.

Localization Workflow Perspective

Comments are especially important when strings are extracted and sent to external localization vendors. Translators often work without direct app context, so notes are their primary hint.

Useful comment content:

• Where text appears.
• Tone requirements, if relevant.
• Placeholder meaning.

For format strings, explain dynamic values clearly.

1let msg = String(format:
2    NSLocalizedString(
3        "cart.items_count",
4        comment: "Label showing number of items in cart, one integer placeholder"
5    ),
6    itemCount
7)

When Empty Comments Are Acceptable

In tiny internal tools with one language and one developer, empty comments might be tolerable. In most products, they become a maintenance cost.

As soon as multiple languages, translators, or teams are involved, meaningful comments should be treated as standard practice.

Key Naming and Comments Together

Comments work best when keys are stable and semantic.

• Prefer keys like checkout.button.confirm.
• Avoid using full source text as key.

Stable keys plus descriptive comments give both engineering and localization teams a predictable system.

Plurals, Formatting, and Comment Quality

Localization is not only key lookup. Pluralization and formatted values need additional context to avoid grammatical errors. When using format placeholders, comment text should explain meaning, units, and expected range.

1let format = NSLocalizedString(
2    "inbox.unread_count",
3    comment: "Message showing unread email count, one integer placeholder"
4)
5let text = String(format: format, unreadCount)

For production apps, also test pseudo-localized builds and long-string languages to confirm UI still reads correctly. Translator comments reduce semantic mistakes, while visual testing catches layout issues such as clipping and truncation. Both are necessary for high-quality localization.

Common Pitfalls

A common pitfall is using identical keys for different contexts to reduce key count. Same source text can require different translations depending on screen meaning.

Another issue is stale comments after feature changes. If UI meaning changes but comments do not, translation quality drops.

Developers also forget to document placeholder semantics, causing format errors or unnatural translations.

Finally, skipping comments for critical user flows like billing and permissions can create expensive production fixes after localization review.

Summary

• The second parameter of NSLocalizedString is a translator comment.
• It is context metadata, not runtime UI text.
• Good comments reduce ambiguity and improve translation quality.
• The same concept applies in advanced localization API variants.
• Keep comments current and aligned with key semantics.