Migration guide

Migrate from Crowdin with your existing translations

Start with one source file and one target language. Import the translations you already trust, compare the files Glossa writes, and keep your current release workflow until the trial passes.

1. Keep a snapshot and choose a small trial

This example uses English source strings, Spanish translations and JSON files. Adapt the paths and locales to your app, and check its format guide before importing a larger catalog.

Save the exact source revision and the translation export together. Run the trial on a separate branch and keep the original files.
File import brings over keys and translation text. Recreate glossary terms, rules and reviewer access separately; screenshots, comments and workflow history do not come with the files.
Check the workspace source locale before pushing. Source and target files must use the same keys and come from the same source revision.

2. Export translation files from Crowdin

With your existing Crowdin CLI configuration, download the target files. In a file-based project the web alternative is Translations → Download as ZIP → Build & Download, which follows the project's export settings.

crowdin download translations --language es --skip-untranslated-strings# For approved translations only:crowdin download translations --language es --export-only-approved --skip-untranslated-strings

Exclude untranslated entries. Crowdin documents that --export-only-approved without --skip-untranslated-strings fills strings without approval with the source language. Imported, that fallback text would look like an existing translation. The second command restricts the export to approved entries.

String-based Crowdin projects export through Target File Bundles instead. Pick a bundle format Glossa reads (see formats).

Crowdin documentation checked 2026-10-29.

3. Import the source, then the translations

Put the files at the example paths in your trial branch. Sign in, create a trial project in agent mode, then push the source before each target file. Agent mode leaves missing strings for your coding agent instead of starting automatic AI translation.

locales/en.json

{  "welcome": "Welcome, {name}!",  "save": "Save changes"}

locales/es.json

{  "welcome": "¡Bienvenido, {name}!",  "save": "Guardar cambios"}

npx @meterapp/glossa loginnpx @meterapp/glossa create_project --json '{"name":"Migration trial","slug":"migration-trial","target_locales":["es"],"translation_mode":"agent","product_context":"An account settings app. Import trial before switching localization tools."}'npx @meterapp/glossa push locales/en.json --project migration-trial --locale ennpx @meterapp/glossa push locales/es.json --project migration-trial --locale esnpx @meterapp/glossa pull --project migration-trial --locale es --out glossa-preview

A target-file push reports translations_imported. Existing translations are stored as imported, and AI translation never overwrites imported, human, reviewed or approved translations.

Imported does not mean approved: Crowdin's approval history is not in these files. Review the imported text before you use a release gate that requires reviewed translations. A project with its own product context keeps its strings apart from the other apps in your workspace.

4. Compare the output before switching

Pull into glossa-preview and compare it with your original target file. For the two-key sample above, the Spanish output holds the same translations and the unchanged name placeholder.

glossa-preview/locales/es.json

{  "welcome": "¡Bienvenido, {name}!",  "save": "Guardar cambios"}

git diff --no-index -- locales/es.json glossa-preview/locales/es.json

The diff exits 1 when the files differ. Investigate each difference: keys, placeholders, plurals and locale paths matter more than whitespace. Build the app and look at its screens. Try a partially translated file too, so missing translations stay visible instead of passing for finished work.

5. Switch one workflow after the trial passes

Save a .glossa.json with the source paths. missing lists the strings left for your agent; check verifies coverage and that your locale files match what Glossa exports. Run the check on the branch you ship.

.glossa.json

{  "project": "migration-trial",  "files": ["locales/en.json"]}

npx @meterapp/glossa missing --project migration-trial --locale esnpx @meterapp/glossa check --project migration-trial

Keep agent mode if your coding agent translates. To have Claude translate future pushes, set the project's translation mode to ai only after every existing target file is imported, and add your glossary and locale rules first.

Then pick one service to write locale files in CI and turn the old writer off. Keep the snapshot and the previous CI configuration until you have shipped and checked a release; they are your rollback path.