Ignorar claves

La CLI de Lingo.dev te permite ignorar claves de traducción específicas para que se excluyan completamente del procesamiento de traducción. Las claves ignoradas no se copian a los archivos de destino y permanecen intactas durante las operaciones de la CLI.

Cuando ignoras claves, la CLI las omite por completo durante el descubrimiento de contenido y la generación de traducciones.

Configurar el ignorado de claves

Añade ignoredKeys a la configuración de tu bucket en i18n.json:

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

El array ignoredKeys utiliza la notación de barra diagonal (/) para especificar claves anidadas y el asterisco (*) para coincidir con múltiples claves.

Cómo funciona el ignorado de claves

Durante el procesamiento de traducción, la CLI de Lingo.dev:

  1. Identifica las claves ignoradas desde tu configuración
  2. Las excluye del descubrimiento de contenido: las claves ignoradas nunca se procesan
  3. Las omite en los archivos de destino: las claves ignoradas no aparecen en las traducciones generadas
  4. Mantiene la separación entre el contenido de desarrollo y producción

Ejemplo de flujo de trabajo:

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

Con la configuración de claves ignoradas:

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

Traducción al español generada:

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

Solo se traducen las claves no ignoradas. Toda la sección internal se excluye de los archivos de destino.

Rutas de claves anidadas

Utiliza la notación de barra diagonal (/) para ignorar claves a cualquier profundidad:

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

Esta notación funciona con estructuras anidadas complejas:

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

La ruta development/logging/level excluye esta configuración de la traducción.

Claves con puntos

La notación de barra diagonal maneja claves que contienen puntos en sus nombres:

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

Ignora estas claves con:

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

Múltiples tipos de bucket

Diferentes formatos de archivo pueden tener diferentes claves ignoradas:

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

Cada tipo de bucket mantiene su propia lista de claves ignoradas según la estructura del contenido.

Ignorar claves vs bloquear claves

Ignorar claves y bloquear claves tienen propósitos diferentes:

Ignorar claves (ignoredKeys):

  • Las claves se excluyen completamente del procesamiento de traducción
  • Las claves ignoradas no aparecen en absoluto en los archivos de destino
  • Se utiliza para desarrollo, pruebas o contenido interno que no debe traducirse

Bloquear claves (lockedKeys):

  • Las claves se incluyen en el procesamiento de traducción pero los valores permanecen sin cambios
  • Las claves bloqueadas aparecen en los archivos de destino con valores de origen idénticos
  • Se utiliza para identificadores técnicos, nombres de componentes o valores que deben permanecer consistentes

Ejemplo comparativo:

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