| name | i18n-messages |
| description | Editing extension i18n message files and their consumers. Use when editing packages/*/src/messages/i18n.ts, adding/changing nls.localize strings, or choosing placeholder tokens (%s/%d/...). |
| review | always |
i18n Messages
Scope:
packages/*/src/messages/i18n.ts + code consuming those messages via nls.localize- NOT
package.json/package.nls.json nls strings (command titles etc.)
- NOT unrelated code
Placeholder semantics
nls.localize(key, ...args) substitutes via node:util.format — packages/salesforcedx-vscode-i18n/src/i18n/message.ts:50 (return format(possibleLabel, ...labelArgs)).
| Token | Use | Behavior (node:util.format) |
|---|
%s | string | string |
%d | count/number | number as-is (3.7→3.7, no truncation) |
%i | integer | truncates float (3.7→3) |
%f | float | float |
%j | value | JSON |
%o %O | value | inspected object |
%c | — | CSS directive, no output |
%% | literal % | % only when args present; bare string skips format() (message.ts:37 args.length > 0 guard) and keeps %% |
%n | NONE | unsupported — renders literal %n, NOT substituted |
Default: counts → %d, strings → %s. (Origin: Removed %n orgs shipped literal %n.)
Arg-count gotcha
message.ts:39 counts specifiers with /%[sdifj%]/g (%% excluded, L40). On mismatch it logs and trims extra args (L41-48); missing args are NOT filled — trailing unmatched tokens render literally.
%o %O %c substitute at runtime but are NOT in that regex → they escape arg-count validation. Avoid relying on them; prefer %s/%d/%j.%n is not counted and not a real token → expected-count is off by what you intended and the %n prints literally.
Reuse first
grep package.nls.json for an existing equivalent before adding — reuse, don't duplicate.
Per-surface style
From salesforcedx-vscode-org (src/messages/i18n.ts, package.nls.json):
| Surface | Example | Cap | Punctuation |
|---|
Command title (package.nls.json *_text) | SFDX: Create a Default Scratch Org... | Title Case, SFDX: prefix | none (... ok for further input) |
| QuickPick/InputBox placeholder | i18n.ts:67 Select scratch orgs and sandboxes to delete | sentence | none |
| Confirm prompt | i18n.ts:68 Permanently delete %d org(s)? This cannot be undone. | sentence | terminal ./? |
Notification (show*Message) | i18n.ts:92 ... orgs expire in the next %d days. ... | sentence | terminal . |
| Button/action label | i18n.ts:69,70 Delete, Logout | Title Case | none |
| Tree/status-bar label+tooltip | i18n.ts:96 Open Default Org in Browser | Title Case | none |
| Log/channel line | — | sentence | . |
| Validation error | — | sentence | terminal . |
No severity prefix
Don't prefix new strings with Error:/Warning: — the show*Message API supplies severity. i18n.ts:92 (Warning: One or more...) is a legacy anti-pattern; don't copy it, and don't edit it (out of scope). See vscode-window-messages.
Cross-ref
vscode-window-messages covers the notification/button API (which show*Message, return values, Effect, modal). This skill is the message text. Don't duplicate API guidance here.
package.json / package.nls.json command titles, menus, and notification slot keys: command-ui.
