Key Ignoring

Lingo.dev CLI allows you to ignore specific translation keys so they are completely excluded from translation processing. Ignored keys are not copied to target files and remain untouched during CLI operations.

When you ignore keys, the CLI skips them entirely during content discovery and translation generation.

Setting Up Key Ignoring

Add ignoredKeys to your bucket configuration in i18n.json:

{
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"],
      "ignoredKeys": ["internal/debug", "dev/settings", "temp/cache"]
    }
  }
}

The ignoredKeys array uses forward slash (/) notation to specify nested keys.

How Key Ignoring Works

During translation processing, Lingo.dev CLI:

1. Identifies ignored keys from your configuration
2. Excludes them from content discovery — ignored keys are never processed
3. Skips them in target files — ignored keys don't appear in generated translations
4. Maintains separation between development and production content

Example workflow:

// locales/en.json (source)
{
  "welcome": "Welcome to our platform",
  "system": {
    "component": "Lingo.dev CLI",
    "version": "1.0.0"
  },
  "internal": {
    "debug": "Debug mode enabled",
    "testData": "Sample test content"
  }
}

With ignored keys configuration:

{
  "ignoredKeys": ["internal/debug", "internal/testData"]
}

Generated Spanish translation:

// locales/es.json (generated)
{
  "welcome": "Bienvenido a nuestra plataforma",
  "system": {
    "component": "Lingo.dev CLI",
    "version": "1.0.0"
  }
}

Only non-ignored keys get translated. The entire internal section is excluded from target files.

Nested Key Paths

Use forward slash (/) notation to ignore keys at any depth:

{
  "ignoredKeys": [
    "development/logging/level",
    "testing/mock/data",
    "admin/internal/config"
  ]
}

This notation works with complex nested structures:

// Source structure
{
  "development": {
    "logging": {
      "level": "verbose"
    }
  }
}

The path development/logging/level excludes this configuration from translation.

Keys with Dots

Forward slash notation handles keys that contain dots in their names:

// Source with dotted key names
{
  "dev": {
    "api.mock": "Mock API enabled",
    "cache.clear": "Clear cache on startup"
  }
}

Ignore these keys with:

{
  "ignoredKeys": ["dev/api.mock", "dev/cache.clear"]
}

Multiple Bucket Types

Different file formats can have different ignored keys:

{
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"],
      "ignoredKeys": ["internal/debug", "dev/settings"]
    },
    "yaml": {
      "include": ["translations/[locale].yml"],
      "ignoredKeys": ["test/data", "admin/config"]
    }
  }
}

Each bucket type maintains its own ignored keys list based on the content structure.

Key Ignoring vs Key Locking

Key ignoring and key locking serve different purposes:

Key Ignoring (ignoredKeys):

• Keys are completely excluded from translation processing
• Ignored keys don't appear in target files at all
• Used for development, testing, or internal content that shouldn't be translated

Key Locking (lockedKeys):

• Keys are included in translation processing but values remain unchanged
• Locked keys appear in target files with identical source values
• Used for technical identifiers, component names, or values that must stay consistent

Example comparison:

// Source file
{
  "welcome": "Welcome",
  "system": {
    "component": "Lingo.dev Engine"
  },
  "internal": {
    "debug": "Debug enabled"
  }
}

// Configuration
{
  "lockedKeys": ["system/component"],
  "ignoredKeys": ["internal/debug"]
}

// Generated target file
{
  "welcome": "Bienvenido",
  "system": {
    "component": "Lingo.dev Engine"
  }
  // internal/debug is completely missing
}