Guides

Migrating from a script

Already have a bin/translate script? locallingo replaces it — here's the swap.

Why migrate#

locallingo is the extracted, maintained version of the bin/translate script that tends to grow inside each app. Moving to it means the same behaviour — AI translation, drift detection, quality linting — but shared across your apps, with a config file instead of hardcoded constants, and the same drift-state format you already have.

The swap#

Add the gem and generate the binstub (see Installation).
Move your script's hardcoded values — target locales, provider/model, prompt context and glossary, language guides — into .locallingo.yml.
Point your existing .i18n-state/ directory at state_dir (the default .i18n-state matches most scripts). Run lingo sync if the format differs.
Replace bin/translate calls in CI and docs with bin/lingo.
Delete the old bin/translate and lib/tools/* files.

Flag → subcommand#

The old flag forms still work (with a deprecation notice), so you can move callers over gradually. The mapping:

old → new

bin/translate --status         → bin/lingo status
bin/translate --translate      → bin/lingo translate
bin/translate --validate       → bin/lingo validate
bin/translate --check-quality  → bin/lingo quality
bin/translate --fix-quality    → bin/lingo fix-quality
bin/translate --sync-state     → bin/lingo sync

Keep the drift state#

If your script tracked source hashes the same way (per-namespace JSON under .i18n-state/), locallingo picks them up as-is — no re-translation needed. If the format differs, run lingo sync once to rebuild the state from your current translations, then commit it.