Wrap a reviewed screen

Turn a small, understood patch into a working localized screen. Review source, catalogs and setup together, then apply the saved plan you inspected.

Prepare, review and apply

polyglot doctor
polyglot start --file src/app/page.tsx --lang fr --route /fr
polyglot wrap --show <plan-id>
polyglot wrap --apply <plan-id>

Run from the app root and replace the example with your actual screen and route. start performs local setup if needed and prints a plan ID. wrap --show reads that saved plan; --apply applies its reviewed bytes. No account is needed for local discovery, planning or wrapping.

For a configured app, use wrap --plan --file src/app/page.tsx to prepare a file plan directly, or wrap --plan to plan the app. --dry-run is a current-source report: it does not by itself identify a durable plan to apply later. Running bare wrap calculates a new transformation.

polyglot wrap --plan --file src/app/page.tsx --json
polyglot wrap --show <plan-id>

Understand the complete patch

• The selected screen’s supported source edits and the imports, catalog entries and runtime setup they require.
• Configuration and dependency changes, including relevant parent workspace manifests and lockfiles. File scope keeps the migration small; it does not remove required companion files.
• Detected app/runtime assumptions, manual candidates and separate validation results. A package installation or build does not prove that the chosen locale renders.

Plans bind source/configuration/dependency inputs and the exact CLI executable. If inputs or the executable change, create a new plan and review the new diff. Do not bypass the refusal by copying edits from an old plan. If the reviewed dependency changes require installation, follow the printed package-manager instructions before running your app; installed caches are not restored by undo.

What can be automated

Coverage depends on the emitter and proven consumer. Supported cases include display text, accessible attributes, interpolation, bounded data consumers and complete rich messages. Metadata helpers and expression-bodied React components are accepted only when their use is proven safe.

For Next.js with next-intl, supported intrinsic code/pre content inside a rich sentence stays owned by the component. Technical code, variables and event behavior are preserved; only surrounding prose and node placeholders enter the message. Unknown callbacks, mutation, ambiguous data consumers or unsupported runtime adapters remain manual.

Server/client boundaries remain part of the review. A library being detected does not establish that every component may call its hooks. Review metadata changes for request and caching behavior, and compare canonical/social URLs after wrapping.

Rich messages and shared data

Keep complete sentences with their placeholders and source-owned elements. The default rich_text setting is true. An unsupported rich transformation receives a precise manual blocker; disabling rich_text is an opt-out that can fragment a sentence and needs careful review.

[translation]
rich_text = true

A scanner finding is not proof that changing an object’s title or label is safe. The same value may feed rendering, a route or a machine comparison. Use the linked data-object guide to expose a bounded display consumer instead of blanket-wrapping property names.

Read counts and validation separately

--strict-wiring returns nonzero on wiring warnings even when edits completed and the report was written. Inspect execution state and the run ID before retrying. Integrations can export the v4 schema with report-schema; unknown schemas must not be treated as a successful run.

Finish the manual remainder

1. Open the source location and read the blocker, affected candidates, repair example and proof condition.
2. Make the smallest framework-appropriate repair: isolate a display value, expose a translator in a proven component scope, or keep an unsupported message manual.
3. Save changes and generate a fresh plan. Recheck verifies that the finding disappeared; it does not verify the screen’s behavior.
4. Exercise visible and accessible text, dynamic values and interactions in the source and target language.

In VS Code, Needs Review supports Defer, Ignore locally, Reopen and Recheck after editing. A local review decision does not alter source, suppress the scanner or change CI policy.

Translate, verify and recover

polyglot translate --plan <plan-id> --languages fr --estimate
polyglot translate --plan <plan-id> --languages fr
polyglot preview --lang fr --route /fr
polyglot runs
polyglot undo <run-id> --diff
polyglot undo <run-id>

Translation is scoped to the saved plan’s changed source keys. Preview runs the app with its current catalogs and does not mark the plan runtime-verified. Use the run ID for recovery, rather than the plan ID. Undo preserves unrelated work and refuses to overwrite later edits; later translation or publication operations can have their own changes and recovery scope.

Continue with

• Saved plans and recovery
• Verify the actual screen
• Repair data ownership
• The VS Code workflow
• Runtime profiles