Migrate to the current CLI
Replace legacy buckets and source fingerprints while preserving accepted translations and a working application.
The current @lingo.dev/cli uses server-side push/pull work and .lingo project state. The older lingo.dev package uses local bucket processing, i18n.json, and i18n.lock. Migrating means preserving the behavior the project needs, not only changing a command name.
Preserve a working starting point #
Record the installed version and preserve source, accepted targets, configuration, and old lockfile in version control. Confirm that the application loads those targets. Keep an existing localization setup's router, provider, language switcher, and catalog loader until a bounded replacement works.
Record the framework/runtime versions and required source, target, and default locales. Test representative locale-prefixed routes, initial detection, fallback, and language switching. Keep those application checks separate from the file-translation migration.
Rebuild file selection #
Create .lingo/config.json with source/target locales and explicit file entries, then link your authorized organization and localization engine. Legacy buckets and fingerprints cannot be renamed into this schema.
The current CLI config supports 22 formats, including HTML (.html and .htm), plain text (.txt, one unit per line as in v0), CSV tables that keep every locale in a column of one file, and Java .properties files (one unit per key as in v0, with lockedKeys, preservedKeys and ignoredKeys matched as in v0, and lockedPatterns in RE2 syntax, which has no lookaround or backreferences). Check a v0 csv bucket file against the CSV layout before moving it. Check a v0 properties bucket's paths against Java properties: a [locale] file name such as messages_[locale].properties becomes a source pattern such as messages_en.properties. CSV-per-locale, MJML, and other legacy-only buckets need a verified conversion or another translation path. Configuration gives the exact enum, matcher, and output templates. Direct-provider model/prompt/base-URL settings from v0 do not belong in this project schema.
Inspect one selected source and its derived target paths before broadening the config. For Markdown-family props, use translateComponentProps.
Adopt and update translations #
Current scoped/bootstrap planning can adopt existing targets. Check representative files and human edits before establishing that baseline: file presence cannot show that values match the latest source.
Backfill fills missing ordinary files, while v0 ordinarily fills missing keys inside existing catalogs. Use current incremental source updates or supported key refresh for that later work. A renamed JSON key is new path-based work even when its text matches an old key; do not rely on v0 content-fingerprint rename reuse.
Unchanged-key target edits can be retained during incremental work. Explicit preserved-key rules add a separate ownership choice. For separate-file formats, whole-file force removes current-target context and can replace accepted wording, so it is not an adoption shortcut.
Complete the first current run #
Follow the current quickstart through backfill and retrieved files. A plain first push without a baseline stores source bytes instead of requesting initial translations. Wait or pull before considering the file workflow complete.
Commit accepted source, target, config, and current lockfile together. The latest-run pointer remains home-local and does not transfer through Git. Separate pull compares hashes; committing a divergent edit alone does not resolve that conflict. lingo check replaces the old frozen-lock gate at file level: it fails when a source changed since .lingo/lock.json or a target file is missing, and it never writes a missing lockfile. Without a committed lockfile it cannot see source changes and checks only that target files exist.
React migration #
The current React workflow extracts literal source/context calls into JSONC and declarations, translates selected catalogs, then loads a runtime string map. Verify one component's fallback, variables, locale switching, and accepted wording before extending the change.
Use Migrate existing React messages and React for the package-specific work. Bundled lingo guide migrate reflects the installed version; it does not establish parity with every earlier generated setup.