I18n Messages
Developmenti18n-messagesI18n Messages is an Agent Skill for development published in the forcedotcom/salesforcedx-vscode repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
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/...).
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/forcedotcom/salesforcedx-vscode/blob/HEAD/.claude/skills/i18n-messages/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/i18n-messages, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
i18n Messages
Scope:
packages/*/src/messages/i18n.ts+ code consuming those messages vianls.localize- NOT
package.json/package.nls.jsonnls 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%csubstitute at runtime but are NOT in that regex → they escape arg-count validation. Avoid relying on them; prefer%s/%d/%j.%nis not counted and not a real token → expected-count is off by what you intended and the%nprints 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.