Игнорирование ключей

Lingo.dev CLI позволяет игнорировать определённые ключи перевода, чтобы они полностью исключались из процесса локализации. Игнорируемые ключи не копируются в целевые файлы и остаются без изменений при работе с CLI.

Когда вы игнорируете ключи, CLI полностью пропускает их при поиске контента и генерации переводов.

Настройка игнорирования ключей

Добавьте ignoredKeys в конфигурацию вашего bucket в i18n.json:

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

Массив ignoredKeys использует слэш (/) для указания вложенных ключей и звёздочку (*) для выбора нескольких ключей.

Как работает игнорирование ключей

Во время обработки перевода Lingo.dev CLI:

  1. Определяет игнорируемые ключи из вашей конфигурации
  2. Исключает их из поиска контента — игнорируемые ключи никогда не обрабатываются
  3. Пропускает их в целевых файлах — игнорируемые ключи не появляются в сгенерированных переводах
  4. Разделяет контент для разработки и продакшена

Пример рабочего процесса:

// 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"
  }
}

С конфигурацией игнорируемых ключей:

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

Сгенерированный испанский перевод:

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

Только неигнорируемые ключи переводятся. Вся секция internal полностью исключается из целевых файлов.

Вложенные пути ключей

Используйте слэш (/), чтобы игнорировать ключи на любом уровне вложенности:

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

Эта запись работает с любыми сложными вложенными структурами:

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

Путь development/logging/level исключает эту конфигурацию из перевода.

Ключи с точками

Слэш-нотация работает и для ключей, в которых есть точки в названии:

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

Игнорируйте эти ключи с помощью:

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

Несколько типов бакетов

Разные форматы файлов могут иметь разные игнорируемые ключи:

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

Каждый тип бакета ведёт свой собственный список игнорируемых ключей в зависимости от структуры контента.

Игнорирование ключей и блокировка ключей

Игнорирование ключей и блокировка ключей нужны для разных задач:

Игнорирование ключей (ignoredKeys):

  • Ключи полностью исключаются из процесса перевода
  • Игнорируемые ключи вообще не попадают в целевые файлы
  • Используется для разработки, тестирования или внутреннего контента, который не должен переводиться

Блокировка ключей (lockedKeys):

  • Ключи включаются в процесс перевода, но значения остаются без изменений
  • Заблокированные ключи отображаются в целевых файлах с исходными значениями
  • Используется для технических идентификаторов, имён компонентов или значений, которые должны оставаться неизменными

Пример сравнения:

// 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
}