Bloqueo de claves

Lingo.dev CLI te permite bloquear claves de traducción específicas para que sus valores permanezcan idénticos en todos los idiomas. Cuando bloqueas claves, la CLI las excluye del procesamiento de traducción y copia los valores de origen directamente a todos los archivos de destino.

Configuración del bloqueo de claves

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

{
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"],
      "lockedKeys": ["system/component", "config/engine", "modules/processor"]
    }
  }
}

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

Cómo funciona el bloqueo de claves

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

1. Identifica las claves bloqueadas de tu configuración
2. Las excluye de la traducción — el contenido bloqueado nunca se envía a los modelos de IA
3. Copia los valores de origen directamente a todos los archivos de destino
4. Mantiene la coherencia en todos los idiomas

Ejemplo de flujo de trabajo:

// locales/en.json (source)
{
  "welcome": "Welcome to our platform",
  "system": {
    "component": "Lingo.dev CLI",
    "processor": "Translation Engine"
  },
  "config": {
    "engine": "Lingo.dev Engine"
  }
}

Con la configuración de claves bloqueadas:

{
  "lockedKeys": ["system/component", "system/processor", "config/engine"]
}

Traducción al español generada:

// locales/es.json (generated)
{
  "welcome": "Bienvenido a nuestra plataforma",
  "system": {
    "component": "Lingo.dev CLI",
    "processor": "Translation Engine"
  },
  "config": {
    "engine": "Lingo.dev Engine"
  }
}

Solo welcome se traduce, mientras que las claves bloqueadas permanecen idénticas al origen.

Sin el bloqueo de claves, "Lingo.dev Engine" podría traducirse erróneamente como "Motor de Lingo.dev" en español o "Lingo.devエンジン" en japonés, lo cual no queremos en este ejemplo.

Rutas de claves anidadas

Utiliza la notación de barra diagonal (/) para bloquear claves en cualquier nivel:

{
  "lockedKeys": [
    "system/engine/component",
    "modules/ai/processor",
    "config/translation/handler"
  ]
}

Esta notación funciona con estructuras anidadas complejas:

// Source structure
{
  "system": {
    "engine": {
      "component": "Lingo.dev Engine"
    }
  }
}

La ruta system/engine/component bloquea el valor del nombre del componente.

Claves con puntos

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

// Source with dotted key names
{
  "modules": {
    "ai.translation": "AI Translation",
    "content.processor": "Content Processor"
  }
}

Bloquea estas claves con:

{
  "lockedKeys": ["modules/ai.translation", "modules/content.processor"]
}

Múltiples tipos de bucket

Diferentes formatos de archivo pueden tener diferentes claves bloqueadas:

{
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"],
      "lockedKeys": ["config/engine", "system/component"]
    },
    "yaml": {
      "include": ["translations/[locale].yml"],
      "lockedKeys": ["service/name", "module/title"]
    }
  }
}

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

Valores de array

Para claves con valores de array, añade /* después del nombre de la clave:

// Source file
{
  "navigation": {
    "menuItems": ["Home", "About", "Contact"],
    "title": "Main Navigation"
  }
}

Bloquea el array con:

{
  "lockedKeys": ["navigation/menuItems/*"]
}

Resultado:

// locales/es.json
{
  "navigation": {
    "menuItems": ["Home", "About", "Contact"],
    "title": "Navegación Principal"
  }
}