Localize one screen in VS Code
Use the First Screen panel to review one complete patch, apply it safely, finish manual findings and verify the localized app.
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 app and executable
- Open the app in a trusted VS Code workspace. In a multi-root workspace, run Polyglot: Choose Project… and confirm the active app.
- For a monorepo, select or open the intended app root rather than assuming the repository root is the app. Use polyglot doctor --apps in a terminal when unsure.
- Save your source/configuration documents, open the real screen file and run Polyglot: Localize one screen from the Command Palette.
- Choose one target language. Local planning needs no hosted account. First Screen probes saved-plan support in the actual CLI.
An older compatible CLI can still scan but cannot provide First Screen. Polyglot: Update CLI downloads the extension’s pinned public version; it does not build the development branch. During candidate testing, set polyglot.binaryPath to the absolute path of your qualified CLI build. Use the matching released extension/CLI when available.
Review the complete diff
First Screen opens a diff document and retains the plan ID in the workspace. Read source, imports, catalogs, configuration and dependency changes together. Review diff reopens that exact plan. Needs Review explains transformations that could not be proven safe.
Apply reviewed plan applies the saved plan. Changed input or executable requires a fresh plan; the extension does not silently approve a new patch. File scope can include required provider/catalog or parent workspace dependency changes.
Save and continue writes the modified documents you choose to save before an on-disk operation. Dismiss the prompt to leave your draft alone. If a document becomes dirty while planning/applying/recovering, the guarded operation cancels and preserves the editor draft; inspect recovery state before retrying.
Estimate, translate and preview
- After apply, choose Estimate translation. It describes local pending work for that screen, not an exact currency quote or a prediction of hosted cache hits.
- Choose Translate screen. Hosted operations need authentication; sign in if required, then rerun that action using the retained plan.
- Choose Preview language. The CLI runs as a VS Code task; inspect the task output and its locale-selection instructions.
- Use the app’s locale control or navigate to the actual localized route. For a custom route, run polyglot preview --lang fr --route /fr/settings in the app terminal.
- Check changing text, accessible names, rich-message handlers, reload and source-language behavior before keeping the patch.
The editor’s Plan applied state means the run committed, not that the app passed a runtime check. Preview’s launch guard does not prevent normal hot-reload editing after launch; later disk edits are protected by recovery conflict checks.
Make Needs Review actionable
| Control | What it does |
|---|---|
| Source location and explanation | Open the affected code; inspect the precise blocker, candidate count, shared cause, example and proof condition. |
| Defer | Retain a local decision with the reason and what would unblock the repair. |
| Ignore locally | Record a reason in this workspace; does not edit source or alter scanner/CI policy. |
| Reopen | Return the finding to active local review. |
| Recheck after editing | Save your repair and run a fresh preview. Disappearance means the finding is no longer reported; verify runtime behavior separately. |
Candidate counts are affected strings. Groups are shared repair units. Prioritize a proven shared repair by its affected candidates, then measure the real editing time. Do not interpret fewer rows as an established accuracy or productivity score.
Resume or undo after interruption
First Screen state persists in the same VS Code workspace and is reconciled with the CLI journal when refreshed. Review diff remains available. If the panel reports Recovery status needs attention, use its recovery diff and refresh actions before continuing. Unavailable journal data is an unverified state, not an applied success.
Undo this plan recovers its associated apply run. The general Review view also exposes Undo this run when a run is known. Save drafts and inspect the recovery diff first. Later edits cause a conflict rather than being discarded. Use the terminal to select a particular preview or approved-pull run:
polyglot runs
polyglot undo <run-id> --diff
polyglot undo <run-id>Return for the next change
- Keep existing catalog keys when moving components. Add meaning context for ambiguous messages in polyglot.toml; changed source or meaning becomes pending again.
- Use Translate… or a language action for incremental work. Add a language through Add Target Language… when you intend to keep it configured.
- Open configured JSON catalogs with Open Translation Editor. Drafts use normal VS Code save/undo; invalid JSON must be repaired as text. YAML remains a text-editor workflow.
- Use Sync Keyed Catalog Identity, review hosted translations, then Pull Approved Translations or Open Translation Pull Request. Pending/rejected translations are excluded from approved publication.
- Run Validate against CI Policy or Show New Findings on This Branch before pushing to compare immutable revisions under the chosen policy.
A local catalog edit or translation request is not a hosted approval. Review and resolve stale/structurally invalid work in the dashboard before publishing. Authentication or provider failures do not justify deleting plans or approvals; fix the cause and resume pending work.