Existing Translations

The Lingo.dev CLI integrates with projects that already have translation files. It compares source keys against existing target files, generates only the missing translations, and leaves your existing work untouched.

How it works#

When you run the CLI on a project with partial translations, it performs a gap analysis:

// locales/en.json (source - 4 keys)
{
  "welcome": "Welcome to our app",
  "button.save": "Save",
  "button.cancel": "Cancel",
  "error.network": "Network error"
}

// locales/es.json (existing - 2 keys translated)
{
  "welcome": "Bienvenido a nuestra aplicación",
  "button.save": "Guardar"
}

Running npx lingo.dev@latest run fills in only the missing keys:

// locales/es.json (after run - all 4 keys present)
{
  "welcome": "Bienvenido a nuestra aplicación",
  "button.save": "Guardar",
  "button.cancel": "Cancelar",
  "error.network": "Error de red"
}

The existing welcome and button.save translations remain unchanged.

First run#

On the first run, the CLI creates an i18n.lock file based on your current state. This lockfile records fingerprints for all source content, ensuring existing translations are not regenerated on subsequent runs - even if they were originally created by a different tool.

Migrating from other tools#

The CLI works with translation files created by any tool, as long as they follow a supported format (JSON, YAML, PO, etc.):

Refreshing translations#

If existing translations have quality issues, you can selectively retranslate:

# Retranslate all Spanish content
npx lingo.dev@latest run --force --target-locale es

# Retranslate a specific key across all languages
npx lingo.dev@latest run --force --key error.network

For more options, see Retranslation.

Next Steps#