Enhanced Message Context

Enhanced Message Context

When implementing Lingui i18n, add translator comments to the messages that need them, so translators have the context to choose the right tone, length, and wording. Which messages need them is the whole question, and the tiers below answer it: a short label carries almost no context of its own and a full sentence carries most of it, so they earn very different treatment.

Know the App Domain First

Before writing comments, identify what the product is about — check package.json description, the README, and route/component names. The domain disambiguates terms that are otherwise unresolvable: in a parking app, "Park" is a parking spot, not a nature park; in a social app, "Post" is likely a noun. Reference the domain in comments whenever a term is domain-sensitive.

When to Add Comments

Prioritize in tiers:

Must comment — translations will be wrong without it:

• Ambiguous short strings: 1-2 word phrases with multiple meanings or parts of speech
  • "Back" (noun or verb?), "Delete" (button or confirmation?), "Close" (verb or adjective?)
• Action labels without a visible object: the code shows what's acted on, the translator can't see it
  • "Remove" (remove what?), "Apply" (apply to what?)
• Domain-sensitive terms: words whose meaning depends on the product
  • "Post" (verb or noun?), "Tag" (noun or verb?), "Park" (spot or greenspace?)
• Grammatical-gender dependence: the translation depends on what the message refers to
  • "Selected" (masculine/feminine/neutral depends on what is selected)
• Unclear placeholders: names that don't reveal what they contain
  • {count} (count of what?), {name} (user name, file name, project name?)

Should comment — quality improves noticeably:

• UI jargon: "Toast", "Drawer", "Chip", "Modal" — component names translators may read literally
• Abbreviations: "Qty", "Avg", "N/A"
• Sentence fragments: text completed by surrounding UI ("per month", "of 24")
• Labels isolated from surroundings: table column headers, tooltips, menu items

Ship uncommented — the message already carries its own context:

• Full, self-explanatory sentences. "We couldn't reach the server. Check your connection and try again." tells a translator everything a location note would. Comment one only where tone or length is genuinely constrained — a 40-character table cell, a legal phrase with a required register.
• Strings whose comment would only restate the text or its file path. "Feature card body text on the features page" attached to a three-sentence paragraph is cost without information.

Plural branches don't need separate comments — one comment on the whole message covers all forms.

Aim for coverage, not saturation

A catalog where nearly every message carries a comment is evidence the tiers were skipped, not evidence of quality. The must-comment tier at 100% is the target; the whole catalog at 100% is not.

Two costs make that real, and both fall on people rather than tooling: comments on everything train translators to skim past comments, so the load-bearing ones stop being read; and every comment is a claim about the UI that rots when the UI moves.

When auditing an existing catalog, measure the must-comment tier specifically rather than overall #. coverage — short messages with no comment are the finding, and a headline percentage hides them. This lists every uncommented entry with its #: reference, which is enough to sort by tier at a glance:

awk -v RS='' '/msgid "[^"]/ && !/#\./' src/locales/en/messages.po

Paragraph mode (RS='') matches against the whole entry, so leave the patterns unanchored — ^msgid only fires on entries that begin with msgid, and most begin with a #: reference line.

t tagged templates cannot carry a comment

This is the single most common way a wrapping pass ends up with no context: the tagged-template form has nowhere to put one.

// ❌ No comment possible — there is no argument to attach one to
<img alt={t`Company logo`} />

// ✅ Object form takes `comment`
<img alt={t({ comment: "Alt text for the logo in the site header", message: "Company logo" })} />

The same applies to msg`…` versus msg({ … }), and to plural(count, { … }) used bare.

Decide the comment while wrapping, not afterwards. For anything in the must-comment tier, reach for the object form the first time. The tagged-template form is the natural thing to type, so leaving it until later turns one decision into a mechanical edit across every attribute, placeholder, and toast in the codebase.

Trans has no such limitation: comment is just a prop, so JSX content can always be commented in place.

<Trans comment="Button in the toolbar that returns to the previous page">Back</Trans>

Leave vendored component libraries alone

Copy inside components/ui/** — shadcn/ui, or any generator-vendored Radix wrapper — is not yours to comment or wrap. shadcn add overwrites those files wholesale, so a macro or a comment added there disappears on the next update, silently and with a green build.

That governs this skill's audit pass too: when a catalog entry's #: reference points into a vendored directory, record it as a known residual and move to the next entry — the file itself stays closed.

If that copy genuinely needs translating, the fix is a project-owned wrapper component that holds the strings and delegates presentation to the primitive — a deliberate design decision for the project, not something a context pass introduces.

Writing Effective Comments

A good translator comment includes:

1. Location: Where in the UI the message appears

   • "Button in the top navigation bar"
   • "Tooltip for the save icon"
   • "Column header in the users table"

2. Action/Purpose: What happens or what it means

   • "Navigates back to the previous page"
   • "Deletes the selected item permanently"
   • "Shows the number of unread notifications"

3. Disambiguation: Clarify part of speech or meaning

   • "Used as a verb, not a noun"
   • "Refers to email addresses, not postal addresses"
   • "Singular form, user will see 'item' or 'items' based on count"