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:
- Existing languages — Only missing translations are generated
- 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.