Preservación de claves

Lingo.dev CLI te permite preservar claves de traducción específicas para que se inicialicen una vez y nunca se sobrescriban en operaciones posteriores de la CLI. Las claves preservadas se copian del origen como marcadores de posición y luego se protegen de actualizaciones automáticas de traducción.

Cuando preservas claves, la CLI las inicializa con valores de origen y luego las omite durante futuras ejecuciones de traducción.

Configuración de la preservación de claves

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

{
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"],
      "preservedKeys": ["legal/privacy", "legal/terms", "marketing/tagline"]
    }
  }
}

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

Cómo funciona la preservación de claves

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

1. Identifica las claves preservadas de tu configuración
2. Las excluye de la traducción — las claves preservadas nunca se envían al motor de traducción
3. Inicializa las claves faltantes — copia los valores de origen como marcadores de posición para nuevos archivos de destino
4. Protege los valores existentes — mantiene sin cambios el contenido traducido manualmente

Ejemplo de flujo de trabajo:

// locales/en.json (source)
{
  "welcome": "Welcome to our platform",
  "legal": {
    "privacy": "We respect your privacy and protect your data.",
    "terms": "By using this service, you agree to our terms."
  }
}

Con configuración de claves preservadas:

{
  "preservedKeys": ["legal/privacy", "legal/terms"]
}

Traducción al español generada (primera ejecución):

// locales/es.json (generated)
{
  "welcome": "Bienvenido a nuestra plataforma",
  "legal": {
    "privacy": "We respect your privacy and protect your data.",
    "terms": "By using this service, you agree to our terms."
  }
}

La clave welcome se traduce. La sección legal se copia tal cual para traducción manual posterior.

Rutas de claves anidadas

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

{
  "preservedKeys": [
    "legal/privacy/full",
    "legal/terms/conditions",
    "marketing/campaigns/holiday"
  ]
}

Esta notación funciona con estructuras anidadas complejas:

// Source structure
{
  "legal": {
    "privacy": {
      "full": "Full privacy policy text..."
    }
  }
}

La ruta legal/privacy/full preserva esta clave anidada específica.

Claves con puntos

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

// Source with dotted key names
{
  "legal": {
    "privacy.policy": "Privacy policy content",
    "terms.of.service": "Terms of service content"
  }
}

Preserva estas claves con:

{
  "preservedKeys": ["legal/privacy.policy", "legal/terms.of.service"]
}

Múltiples tipos de bucket

Los diferentes formatos de archivo pueden tener diferentes claves preservadas:

{
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"],
      "preservedKeys": ["legal/privacy", "legal/terms"]
    },
    "yaml": {
      "include": ["translations/[locale].yml"],
      "preservedKeys": ["compliance/gdpr", "compliance/ccpa"]
    }
  }
}

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

Preservación de claves vs bloqueo de claves

La preservación de claves y el bloqueo de claves tienen propósitos diferentes:

Preservación de claves (preservedKeys):

• Las claves se inicializan una vez con valores de origen como marcadores de posición
• Los valores de destino existentes nunca se sobrescriben por la CLI
• Se utiliza para contenido que requiere traducción manual o revisión legal

Bloqueo de claves (lockedKeys):

• Las claves se incluyen en el procesamiento de traducción pero los valores permanecen sin cambios
• Las claves bloqueadas siempre coinciden exactamente con los valores de origen
• 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"
  },
  "legal": {
    "privacy": "Privacy policy text"
  }
}

// Configuration
{
  "lockedKeys": ["system/component"],
  "preservedKeys": ["legal/privacy"]
}

// Generated target file
{
  "welcome": "Bienvenido",
  "system": {
    "component": "Lingo.dev Engine"
  },
  "legal": {
    "privacy": "Privacy policy text"
  }
}

Después de traducir manualmente legal/privacy al español, las ejecuciones posteriores mantienen la traducción manual. La clave system/component siempre permanece en inglés independientemente del contenido del archivo de destino.