键忽略

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

多种 Bucket 类型

不同的文件格式可以有不同的忽略键：

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

每种 bucket 类型会根据内容结构维护自己的忽略键列表。

键忽略与键锁定

键忽略 和 键锁定 用途不同：

键忽略（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
}