Adding Languages

Lingo.dev CLI makes it simple to expand your project to new languages by adding target locales to your i18n.json configuration and running a single command.

When you add new languages, the CLI generates complete translation files for the new locales while preserving all existing translations and maintaining the same content fingerprinting system.

Adding Your First New Language

To add a new language, update the targets array in your i18n.json configuration:

Original configuration:

{
  "locale": {
    "source": "en",
    "targets": ["es", "fr"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"]
    }
  }
}

Updated configuration with German:

{
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"]
    }
  }
}

Running npx lingo.dev@latest i18n creates the new German translation file:

locales/
  en.json    (source - unchanged)
  es.json    (existing - unchanged)
  fr.json    (existing - unchanged)
  de.json    (new - fully translated)

How New Language Generation Works

Lingo.dev CLI treats new languages differently from existing ones:

1. Existing languages — Only missing translations are generated
2. New languages — Complete translation files are created from scratch

Example with partial existing translations:

// locales/en.json (source)
{
  "welcome": "Welcome",
  "button.save": "Save",
  "error.network": "Network error"
}

// locales/es.json (existing with missing translations)
{
  "welcome": "Bienvenido"
}

After adding German and running the CLI:

// locales/es.json (gaps filled)
{
  "welcome": "Bienvenido",
  "button.save": "Guardar",
  "error.network": "Error de red"
}

// locales/de.json (complete new file)
{
  "welcome": "Willkommen",
  "button.save": "Speichern",
  "error.network": "Netzwerkfehler"
}

Adding Multiple Languages

You can add multiple languages simultaneously:

{
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de", "ja", "zh"]
  }
}

The CLI processes all new languages, creating complete translation files for each new locale.

Regional Variants

Lingo.dev CLI supports regional language variants using BCP 47 language tags:

{
  "locale": {
    "source": "en-US",
    "targets": ["en-GB", "es-ES", "es-MX", "fr-FR", "fr-CA"]
  }
}

This generates distinct translation files for each regional variant, accounting for differences in terminology, spelling, and cultural context.

File Structure Impact

The CLI creates new files following your bucket patterns. For different file formats:

JSON buckets:

locales/[locale].json → locales/de.json, locales/ja.json

Markdown buckets:

content/[locale]/*.md → content/de/*.md, content/ja/*.md

Nested structures:

app/[locale]/messages.json → app/de/messages.json, app/ja/messages.json

Targeted Language Addition

You can generate translations for specific new languages using the --locale flag:

npx lingo.dev@latest i18n --locale de

This generates only German translations, leaving other new languages for later processing.

Language Removal

To remove a language, simply remove it from the targets array. The CLI won't delete existing files, but it will stop processing that locale:

{
  "locale": {
    "source": "en",
    "targets": ["es", "fr"]
  }
}

You can manually delete the corresponding translation files if needed.