Skip to content

docs(sdk): action handlers must i18n what they throw - #3659

Open
MattDHill wants to merge 1 commit into
live-docsfrom
fix/i18n-thrown-action-errors
Open

docs(sdk): action handlers must i18n what they throw#3659
MattDHill wants to merge 1 commit into
live-docsfrom
fix/i18n-thrown-action-errors

Conversation

@MattDHill

@MattDHill MattDHill commented Aug 11, 2026

Copy link
Copy Markdown
Member

The i18n() convention in actions.md carved out thrown errors:

Thrown errors are the exception. throw new Error(...) messages are developer-facing diagnostics that surface in logs and stack traces, not translated UI copy — leave them as plain strings and do not wrap them in i18n().

For an action handler the premise is false. ActionService.execute catches the error and renders the message straight into an alert dialog labelled "Error" — action.service.ts:78-81. That alert is the only thing telling the user the action failed, so the guide was directing packagers to leak English into it in every non-default locale. Found while auditing ppq-private-mode-startos, whose "An API key is required…" message is exactly this case; the CLI shows the same string (Action Failed: Error: An API key is required…).

Wrapping it works end to end, which the old wording also left unclear:

  • setupI18n resolves eagerly against the container's LANG and returns a finished string (i18n/index.ts:29,62-64), so what crosses the wire is already translated.
  • i18nPipe looks the string up in ENGLISH and falls through to the input verbatim on a miss (i18n.pipe.ts:16-18), so a package-translated message renders as-is rather than as a missing-key artifact.

The exception is real for throws that aren't in an action. setupMain / setupInit / migration failures land in statusInfo.error and render as a Service Launch Error card next to Rebuild and Uninstall buttons (error.component.ts) — a crash report, not copy. So the rule is split by throw site rather than deleted.

init.md:233's plain-string throw new Error('Bootstrap failed') sits in runUntilSuccess bootstrap and stays correct under the new wording. No other page states the old rule.

Targeting live-docs rather than master: the wrong sentence is on docs.start9.com now, and what it gets wrong is how shipped StartOS already behaves — not an unreleased SDK surface — so this is a correction to the published site rather than a doc riding along with its code. docs-backport.yml pushes the same commit to master on merge, so it lands in both without being written twice. No CHANGELOG.md entry: book-only, no change to the SDK's shipped surface.

@MattDHill
MattDHill changed the base branch from master to live-docs August 11, 2026 18:03
@MattDHill
MattDHill changed the base branch from live-docs to master August 11, 2026 18:03
The i18n convention told packagers to leave thrown errors as plain
strings on the grounds that they are diagnostics that only reach logs.
For an action handler that is wrong: action.service.ts catches the
error and renders the message as the alert that reports the failure, so
it is the user's only feedback and English leaks into every non-default
locale.

Split the rule by where the throw happens. Action handlers translate;
setupMain/setupInit/migrations stay plain, since those surface as a
Service Launch Error crash report rather than composed copy.
@MattDHill
MattDHill force-pushed the fix/i18n-thrown-action-errors branch from d85a25f to 9c7e7f8 Compare August 11, 2026 18:27
@MattDHill
MattDHill changed the base branch from master to live-docs August 11, 2026 18:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant