键忽略

Lingo.dev CLI 允许您忽略特定的翻译键，使其完全排除在翻译处理之外。被忽略的键不会被复制到目标文件，并且在 CLI 操作期间保持不变。

当您忽略键时，CLI 在内容发现和翻译生成过程中会完全跳过它们。

设置键忽略

在 i18n.json 的存储桶配置中添加 ignoredKeys：

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

ignoredKeys 数组使用正斜杠（/）表示法来指定嵌套键。

键忽略的工作原理

在翻译处理过程中，Lingo.dev CLI：

从配置中识别被忽略的键
从内容发现中排除它们——被忽略的键不会被处理
在目标文件中跳过它们——被忽略的键不会出现在生成的翻译中
保持开发内容与生产内容的分离

示例工作流程：

// locales/en.json (源文件)
{
  "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 (生成文件)
{
  "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"
  ]
}

此表示法适用于复杂的嵌套结构：

// 源结构
{
  "development": {
    "logging": {
      "level": "verbose"
    }
  }
}

路径 development/logging/level 将此配置从翻译中排除。

含有点号的键

正斜杠表示法可以处理名称中包含点号的键：

// 含有点号键名的源文件
{
  "dev": {
    "api.mock": "启用 Mock API",
    "cache.clear": "启动时清除缓存"
  }
}

可以通过以下方式忽略这些键：

{
  "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)：

键包含在翻译处理中，但值保持不变
锁定的键会出现在目标文件中，且值与源文件相同
用于技术标识符、组件名称或必须保持一致的值

示例对比：

// 源文件
{
  "welcome": "欢迎",
  "system": {
    "component": "Lingo.dev 引擎"
  },
  "internal": {
    "debug": "启用调试"
  }
}

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

// 生成的目标文件
{
  "welcome": "欢迎",
  "system": {
    "component": "Lingo.dev 引擎"
  }
  // internal/debug 完全缺失
}