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 of their own

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>

The directive escape hatch

A lingui-set directive sets comment for every macro that follows it in the file, tagged templates included. It is the only way to give t`…` a comment without rewriting it:

// lingui-set comment="Alt text for the logos in the site header"
<img alt={t`Company logo`} />
<img alt={t`Partner logo`} />
// lingui-reset

Reach for it only when a block of messages genuinely shares one description — a toolbar, a table, an empty state. A directive spanning a file of unrelated strings attaches the same words to all of them, which is the saturation the tiers exist to prevent rather than a shortcut around the object form.

Close it with lingui-reset. An open directive keeps applying to messages added to the file later, so its comment ends up describing strings nobody wrote it for, and it changes the IDs extracted for any of them that also inherit a context.

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:

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"
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"
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"

Quality Rules

Describe where it appears and what it refers to — not what the word means.
- Bad: "Save — means to store"
- Good: "Save button in the document editor toolbar"
Keep it under ~80 characters. A comment is a hint, not documentation.
Reference the app domain when the term is domain-sensitive: "Park — a parking spot, not a nature park"
Write comments in the source language of the project.
Use consistent terminology across all comments (same words for the same UI areas).

comment vs context

They solve different problems — don't mix them up:

comment is advice for the translator. It never changes the message identity.
context changes the message ID: the same text with two context values becomes two catalog entries translated independently. Use it only when the same source text genuinely needs different translations ("right" as direction vs. correctness).
Never use context as a namespace (auth.login, settings.title). Identical strings with identical meaning should share one catalog entry; namespacing splits them into duplicate translation work.

API Reference

Lingui provides three ways to add translator comments:

1. JS Macro (`t`)

For JavaScript code outside JSX:

import { t } from "@lingui/core/macro";

// With comment
const backLabel = t({
  comment: "Button in the navigation bar that returns to the previous page",
  message: "Back",
});

// With comment and variable
const uploadSuccess = t({
  comment: "Success message showing the name of the file that was uploaded",
  message: `File ${fileName} uploaded successfully`,
});

2. React Macro (`Trans`)

For JSX elements:

import { Trans } from "@lingui/react/macro";

// With comment
<Trans comment="Button that deletes the selected email message">Delete</Trans>

// With comment in a component
<button>
  <Trans comment="Label for button that saves changes to user profile">
    Save
  </Trans>
</button>

3. Deferred/Lazy Messages (`defineMessage` / `msg`)

For messages defined separately from their usage:

import { defineMessage } from "@lingui/core/macro";

const messages = {
  deleteButton: defineMessage({
    comment: "Button that permanently removes the item from the database",
    message: "Delete",
  }),

  statusLabel: defineMessage({
    comment: "Shows whether the service is currently operational. Values: 'Active', 'Inactive', 'Pending'",
    message: "Status: {status}",
  }),
};

Examples

Example 1: Ambiguous Short Word

Before (no context):

<button onClick={goBack}>
  <Trans>Back</Trans>
</button>

After (with context):

<button onClick={goBack}>
  <Trans comment="Button in the toolbar that navigates to the previous page">
    Back
  </Trans>
</button>

Example 2: UI Label Without Context

Before (no context):

const columns = [
  { key: "name", label: t`Name` },
  { key: "status", label: t`Status` },
];

After (with context):

const columns = [
  { 
    key: "name", 
    label: t({
      comment: "Column header in the projects table showing project name",
      message: "Name"
    })
  },
  { 
    key: "status", 
    label: t({
      comment: "Column header showing project status: Active, Inactive, or Archived",
      message: "Status"
    })
  },
  { 
    key: "created", 
    label: t({
      comment: "Column header showing the date when the project was created",
      message: "Created"
    })
  },
];

Example 3: Domain-Specific Term

Before (ambiguous):

<button onClick={handlePost}>
  <Trans>Post</Trans>
</button>

After (clarified as verb):

<button onClick={handlePost}>
  <Trans comment="Button that publishes the content. Used as a verb (to post), not a noun (a post)">
    Post
  </Trans>
</button>

Example 4: Variable Without Clear Meaning

Before (unclear what count represents):

const message = t`${count} items selected`;

After (clarified):

const message = t({
  comment: "Shows the number of email messages currently selected in the inbox",
  message: `${count} items selected`,
});

Example 5: Self-Explanatory Message (Lower Priority, Still Valuable)

// Message is clear on its own; adding a comment with location still helps translators
<Trans comment="Validation hint shown below the password field on the sign-up form">
  Your password must contain at least 8 characters, including one uppercase letter and one number.
</Trans>

Workflow

When implementing or reviewing Lingui messages:

Know the domain: Identify what the app is about (see above) so comments can disambiguate domain terms
Read the message: Look at the string itself
Check context: Consider where and how it's used in the code
Ask: "Could a translator misinterpret this without seeing the UI?"
If yes: reach for the object form (t({ comment, message }), Trans comment=…) at the moment you wrap, and give it location, purpose, and any disambiguation
If no: leave it uncommented and move on. A self-explanatory sentence does not need a location note, and adding one costs more than it returns

Post-Extraction Review Pass

After a batch of i18n work, audit the catalog instead of trusting that comments were added along the way:

Run lingui extract
Scan the source-locale .po file for entries with no #. line (that's where comment lands)
Triage by tier — do not treat every uncommented entry as a defect. Short or ambiguous strings, unclear placeholders and domain terms go back to the source and get a comment. Full self-explanatory sentences are a correct outcome, not a gap
Skip entries whose #: reference points into a vendored directory (components/ui/**) and record them as known residuals
Re-run lingui extract and confirm the #. lines appear

Report the result as the must-comment tier's coverage plus what you deliberately left alone — "every short label commented, 120 self-explanatory sentences left as-is, 25 vendored residuals" — rather than a single catalog-wide percentage, which cannot distinguish those three.

Enforcing it with ESLint

eslint-plugin-lingui 0.16 and later ships a require-comment rule that reports messages with no description, at the source and with a file and line, rather than after extraction. A blank comment is reported too.

The rule is off by default and, as configured out of the box, requires a comment on every message — which is exactly the saturation the tiers argue against. Turning it on globally is not the goal. Two ways it does fit:

As the audit pass, temporarily. Enable it at warn over a directory to enumerate what is uncommented, triage by tier, then turn it off. Replaces the awk scan above and runs before lingui extract.
Scoped to directories where the must-comment tier is dense — toolbars, table and column definitions, icon-button labels, empty states. There, "every message" and "every message that needs one" are nearly the same set, so a permanent ESLint overrides entry costs little.

Two options matter for this skill's advice: allowContext: true accepts a context in place of a comment, and ignorePatterns strips metadata tags such as [CHAR_LIMIT=40] so that a comment carrying only metadata is still reported as missing a description.

A lingui-set comment="…" directive satisfies the rule for the messages it covers. If directives are used that way, enable require-directive-reset alongside it, which reports a lingui-set that is never closed.

#. Button in the toolbar that navigates to the previous page
#: src/components/Toolbar.tsx:24
msgid "Back"
msgstr ""

Notes

Comments are extracted into message catalogs for translators
Comments are stripped from production builds — zero runtime cost, which is not the same as zero cost: the cost is a translator's attention and a maintainer's upkeep, and that is what the tiers ration
Comments appear in translation management systems (TMS)
Use consistent terminology across all comments in your project

enhanced-message-context