OpenParable
Skip to content
← Back to skills

I18n Messages

Development
i18n-messages

I18n 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/...).

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
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 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)).

TokenUseBehavior (node:util.format)
%sstringstring
%dcount/numbernumber as-is (3.7→3.7, no truncation)
%iintegertruncates float (3.7→3)
%ffloatfloat
%jvalueJSON
%o %Ovalueinspected object
%c—CSS directive, no output
%%literal %% only when args present; bare string skips format() (message.ts:37 args.length > 0 guard) and keeps %%
%nNONEunsupported — 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):

SurfaceExampleCapPunctuation
Command title (package.nls.json *_text)SFDX: Create a Default Scratch Org...Title Case, SFDX: prefixnone (... ok for further input)
QuickPick/InputBox placeholderi18n.ts:67 Select scratch orgs and sandboxes to deletesentencenone
Confirm prompti18n.ts:68 Permanently delete %d org(s)? This cannot be undone.sentenceterminal ./?
Notification (show*Message)i18n.ts:92 ... orgs expire in the next %d days. ...sentenceterminal .
Button/action labeli18n.ts:69,70 Delete, LogoutTitle Casenone
Tree/status-bar label+tooltipi18n.ts:96 Open Default Org in BrowserTitle Casenone
Log/channel line—sentence.
Validation error—sentenceterminal .

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.