Conservation des clés

Le CLI Lingo.dev vous permet de conserver des clés de traduction spécifiques afin qu'elles soient initialisées une seule fois et jamais écrasées par les opérations CLI ultérieures. Les clés conservées sont copiées depuis la source comme espaces réservés, puis protégées contre les mises à jour automatiques de traduction.

Lorsque vous conservez des clés, le CLI les initialise avec les valeurs sources puis les ignore lors des futures exécutions de traduction.

Configuration de la conservation des clés

Ajoutez preservedKeys à la configuration de votre bucket dans i18n.json :

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

Le tableau preservedKeys utilise la notation barre oblique (/) pour spécifier les clés imbriquées et l'astérisque (*) pour correspondre à plusieurs clés.

Fonctionnement de la conservation des clés

Lors du traitement de la traduction, le CLI Lingo.dev :

1. Identifie les clés conservées depuis votre configuration
2. Les exclut de la traduction — les clés conservées ne sont jamais envoyées au moteur de traduction
3. Initialise les clés manquantes — copie les valeurs sources comme espaces réservés pour les nouveaux fichiers cibles
4. Protège les valeurs existantes — conserve le contenu traduit manuellement inchangé

Exemple de flux de travail :

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

Avec la configuration des clés conservées :

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

Traduction espagnole générée (première exécution) :

// 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 clé welcome est traduite. La section legal est copiée telle quelle pour une traduction manuelle ultérieure.

Chemins de clés imbriquées

Utilisez la notation barre oblique (/) pour conserver des clés à n'importe quelle profondeur :

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

Cette notation fonctionne avec des structures imbriquées complexes :

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

Le chemin legal/privacy/full conserve cette clé imbriquée spécifique.

Clés contenant des points

La notation barre oblique gère les clés qui contiennent des points dans leurs noms :

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

Préservez ces clés avec :

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

Types de buckets multiples

Différents formats de fichiers peuvent avoir différentes clés préservées :

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

Chaque type de bucket maintient sa propre liste de clés préservées en fonction de la structure du contenu.

Préservation de clés vs verrouillage de clés

La préservation de clés et le verrouillage de clés servent des objectifs différents :

Préservation de clés (preservedKeys) :

• Les clés sont initialisées une fois avec les valeurs sources comme espaces réservés
• Les valeurs cibles existantes ne sont jamais écrasées par le CLI
• Utilisé pour le contenu nécessitant une traduction manuelle ou une révision juridique

Verrouillage de clés (lockedKeys) :

• Les clés sont incluses dans le traitement de traduction mais les valeurs restent inchangées
• Les clés verrouillées correspondent toujours exactement aux valeurs sources
• Utilisé pour les identifiants techniques, les noms de composants ou les valeurs qui doivent rester cohérentes

Exemple de comparaison :

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

Après avoir traduit manuellement legal/privacy en espagnol, les exécutions suivantes conservent la traduction manuelle. La clé system/component reste toujours en anglais quel que soit le contenu du fichier cible.