docs(sdk): action handlers must i18n what they throw - #3659
Open
MattDHill wants to merge 1 commit into
Open
Conversation
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
force-pushed
the
fix/i18n-thrown-action-errors
branch
from
August 11, 2026 18:27
d85a25f to
9c7e7f8
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The
i18n()convention inactions.mdcarved out thrown errors:For an action handler the premise is false.
ActionService.executecatches 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 auditingppq-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:
setupI18nresolves eagerly against the container'sLANGand returns a finished string (i18n/index.ts:29,62-64), so what crosses the wire is already translated.i18nPipelooks the string up inENGLISHand 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 instatusInfo.errorand 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-stringthrow new Error('Bootstrap failed')sits inrunUntilSuccessbootstrap and stays correct under the new wording. No other page states the old rule.Targeting
live-docsrather thanmaster: 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.ymlpushes the same commit tomasteron merge, so it lands in both without being written twice. NoCHANGELOG.mdentry: book-only, no change to the SDK's shipped surface.