Troubleshooting and support
Find the failed stage, preserve local work and use a concrete recovery path before retrying.
These guides use CLI 0.14.4 and the extension 0.7.2 workflow. Install or update the CLI before starting. Confirm that polyglot start --help and polyglot wrap --help expose saved plans. In VS Code, use an extension build that includes Localize one screen and run Update CLI if your selected binary is older.
Download the extension below, then open the VS Code Command Palette and run Extensions: Install from VSIX. Select the downloaded file.
Choose the next action
| Symptom | Next action |
|---|---|
| start is unknown / First Screen unavailable | Inspect the selected CLI path and help. Install CLI 0.14.3 or newer with saved-plan support, and update any explicit binary path that still selects an older installation. |
| Wrong app or unresolved runtime | Run doctor --apps, enter the app root and run doctor. Check installed dependencies and the actual loader. |
| Saved plan is stale | Inspect changed inputs or CLI binary; generate and review a new plan. |
| Command failed but files changed | Read execution state and runs; inspect undo <run-id> --diff before another mutation. |
| Recovery conflict / pending recovery | Preserve your later edits and compare the original/expected/current file. Resolve the named conflict; do not delete the journal to bypass protection. |
| Source text still appears in target locale | Confirm the route/cookie/runtime locale, catalog path and loaded keys. Use distinctive pseudo text to distinguish real activation from fallback. |
| No automatic changes | Open Needs Review and its proof conditions. An empty diff is not a successful localized screen. |
| Hosted translation or sign-in fails | Run auth status, sign in if needed, check project binding and retry pending work. Keep the saved plan and successful translations. |
| Translation save conflicts | Keep your draft, refresh the current revision, reconcile the competing edit and resubmit. Structural errors identify content to repair before approval. |
An ICU translation is withheld
Choice bodies are translatable prose. In the example below, Member and Guest are not argument names. Keep selector identifiers, exact-number branches, offsets, formatter styles, nested variables and plural # counts intact. Target-language plural categories may expand using an existing argument structure.
{role, select, member {Member} other {Guest}}Malformed or unsupported structures are withheld from materialization. Correct the message in the review workbench and retry; generated text still needs semantic review by default. Passing structure checks does not verify the translation’s meaning or your runtime build.
Prepare a private support attachment
polyglot doctor
polyglot doctor --diagnostics polyglot-support.jsondoctor shows detailed local discovery. The diagnostic command writes a new private JSON file and never uploads it. It contains the executable hash, OS/architecture, runtime classification, numeric installed version and bounded discovery counts. A broken configuration can still produce project_discovery: unavailable.
The bundle excludes source, catalog values, file paths, account identity, credentials, environment variables, commands, URLs and raw errors. It refuses to overwrite an existing file and remains below 64 KiB. Inspect it before choosing to share it. Recovery records and screenshots can contain proprietary content and are not included.
Opt in to a first-use study
polyglot study --enable
# Complete the first-screen journey in the same configured app.
polyglot study --record runtime_verified
polyglot study --record patch_kept
polyglot study --exportEnable only after local configuration exists and only if you want to record this session. Nothing is uploaded. Records contain a random session ID, framework/runtime profile and version, elapsed times and fixed event names. Plan/apply/recovery events are observed by the CLI after opt-in; runtime_verified and patch_kept are your own confirmations.
Record assistance_required when help is needed, or abandoned when you stop. Failed or assisted attempts belong in the study, not just successes. An applied patch or a copied dashboard command does not establish unassisted completion.
polyglot study --record assistance_required
polyglot study --record abandoned
polyglot study --disableExport only if you choose to share the records. --disable deletes the local session; export first if you want to keep it, then disable before starting a separate attempt. Developer effort, cold installation, native SDK setup and semantic language review need separate observation.