i18n.json Configuration

i18n.json is a standard configuration file that controls the behavior of Lingo.dev CLI and Lingo.dev CI/CD integrations.

i18n.json implements a schema-driven configuration that separates language settings, file discovery patterns, and AI translation engine configuration into distinct sections. As a result, developers understand exactly how their localization workflow operates by reading the configuration file.

This guide assumes you have Lingo.dev CLI installed and are configuring a translation workflow. Upon completion, you will understand the complete i18n.json structure, configuration options, and how each section controls translation behavior.

Version

The version field specifies the configuration schema version:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": 1.8
}

Configuration elements:

  • $schema — Points to the JSON schema definition for IDE autocompletion and validation. The schema helps catch configuration errors early by providing inline documentation and type checking.
  • version — Configuration schema version for migration compatibility.

Lingo.dev CLI uses this field for automatic configuration migration when new schema versions are released.

Locale Configuration

The locale section defines which languages Lingo.dev CLI processes:

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

Language codes follow the BCP 47 standard for language tags, which incorporates language codes from ISO 639 and optional region codes from ISO 3166-1. Examples include en, en-US, es-ES, and zh-Hans.

Lingo.dev CLI also supports platform-specific locale formats like Android's en-rUS convention for resource directories. To get the full list of supported locale codes, run:

npx lingo.dev@latest show locale sources  # Available source languages
npx lingo.dev@latest show locale targets  # Available target languages

If your locale code is not supported, please open a pull request to add it!

Configuration elements:

  • locale.source — Source language code that identifies which files contain the authoritative content. All translations flow from source to targets.
  • locale.targets — Array of target language codes representing your target markets. Each code corresponds to a separate file or section within a file, depending on format.

Language verification commands:

Provider Configuration

The provider section determines which AI translation service Lingo.dev CLI uses. This section is optional and defaults to Lingo.dev's AI translation engine when omitted.

For raw LLM API access:

{
  "provider": {
    "id": "openai",
    "model": "gpt-4o-mini",
    "prompt": "Your custom translation prompt with {source} and {target} placeholders"
  }
}

For Lingo.dev Engine:

To use Lingo.dev Engine, omit the provider section entirely. The engine automatically selects models and prompts based on optimization research, and your Lingo.dev Engine settings.

Configuration elements:

  • provider.id — AI translation service identifier (e.g. "openai" or "anthropic").
  • provider.model — AI translation model name (e.g. "gpt-4o-mini" for OpenAI or "claude-3-haiku" for Anthropic).
  • provider.prompt — System prompt that guides translation behavior. The {source} and {target} placeholders are replaced with actual language codes at runtime.

Buckets Configuration

Buckets define file discovery patterns and processing rules. Each bucket represents a file format with specific include/exclude patterns.

{
  "buckets": {
    "json": {
      "include": ["locales/[locale].json", "app/[locale]/*.json"],
      "exclude": ["locales/[locale]/internal.json"],
      "lockedKeys": ["app/version", "config/apiUrl"],
      "injectLocale": ["settings.language"]
    },
    "markdown": {
      "include": ["docs/[locale]/*.md"],
      "exclude": ["docs/[locale]/drafts/*.md"]
    }
  }
}

Configuration elements:

  • buckets.[bucket-type] — Configuration group for a specific file format bucket.
    • buckets.[bucket-type].include — Array of file discovery patterns. Can contain strings or objects.
      • buckets.[bucket-type].include.[string] — Simple file path pattern with [locale] placeholder.
      • buckets.[bucket-type].include.[object] — Advanced pattern configuration with the following properties:
        • path — The file path pattern with [locale] placeholder.
        • delimiter — The delimiter to use for locale codes. Defaults to - (dash), can be overridden to _ (underscore). Overrides the delimiter from the locale configuration.
    • buckets.[bucket-type].exclude — Array of file exclusion patterns to skip during processing.
    • buckets.[bucket-type].lockedKeys — Array of keys that should not be translated. Uses forward slash / as separator for nested keys.
    • buckets.[bucket-type].ignoredKeys — Array of keys that should be ignored during translation. Uses forward slash / as separator for nested keys.
    • buckets.[bucket-type].injectLocale — Array of keys where the locale code should be automatically injected.

Basic Pattern Structure

Include patterns use glob-like syntax with the special [locale] placeholder:

  • locales/[locale].json → locales/en.json, locales/es.json
  • docs/[locale]/*.md → docs/en/*.md, docs/es/*.md

Exclude patterns prevent processing of specific files within include patterns.

Advanced Pattern Options

Custom locale delimiters for different filename formats:

{
  "include": [
    "standard/[locale].json",
    {
      "path": "underscore/[locale].json",
      "delimiter": "_"
    }
  ]
}

Available delimiters:

  • - (dash): en-US.json
  • _ (underscore): en_US.json

Tip: This setting controls the delimiter used in the file name, so you can use it in a monorepo setup that where different projects have different delimiter conventions.

Supported Bucket Types

Lingo.dev CLI supports the following bucket types for different file formats:

  • android — Android XML resource files
  • csv — CSV files with separate files for each target language
  • flutter — Flutter ARB files
  • html — HTML files with separate files for each target language
  • json — JSON files with separate files for each target language
  • markdown — Markdown files with separate files for each target language
  • mdx — MDX files with separate files for each target language
  • xcode-strings — Legacy Xcode .strings files
  • xcode-stringsdict — Xcode .stringsdict files for pluralization
  • xcode-xcstrings — Xcode strings catalog files
  • yaml — YAML files with separate files for each target language
  • yaml-root-key — YAML files with locale-based root keys
  • properties — Java .properties files
  • po — GNU gettext .po files
  • xml — Generic XML files with separate files for each target language
  • php — PHP array files
  • vue-json — Vue.js i18n JSON files
  • typescript — TypeScript files with separate files for each target language

Configuration Examples

Basic Configuration

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": 1.8,
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "ja"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"]
    }
  }
}

Monorepo Configuration

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": 1.8,
  "locale": {
    "source": "en-US",
    "targets": ["es-ES", "fr-FR"]
  },
  "buckets": {
    "json": {
      "include": ["apps/web/locales/[locale].json"]
    },
    "mdx": {
      "include": ["packages/docs/content/[locale]/*.mdx"]
    },
    "xcode-xcstrings": {
      "include": ["ios/Localizable.xcstrings"]
    },
    "android": {
      "include": ["android/values-[locale]/strings.xml"]
    }
  }
}

Version Migration

i18n.json implements smart version migration that automatically updates your configuration to newer schema versions while preserving all user settings.

When Lingo.dev CLI detects an older configuration version, it:

  1. Creates a backup of your current i18n.json file
  2. Migrates configuration to the latest schema version
  3. Preserves all settings including custom providers, bucket configurations, and locked keys
  4. Updates the version field to match the current schema

Migration behavior:

Migration triggers automatically during any CLI operation that reads the configuration file. No manual intervention is required, and your translation workflow continues without interruption.

This migration system ensures i18n.json configurations remain compatible with Lingo.dev CLI updates while maintaining backward compatibility with existing projects.