Schlüsselbewahrung

Die Lingo.dev CLI ermöglicht es Ihnen, bestimmte Übersetzungsschlüssel zu bewahren, sodass sie einmalig initialisiert und bei nachfolgenden CLI-Operationen nie überschrieben werden. Bewahrte Schlüssel werden als Platzhalter aus der Quelle kopiert und dann vor automatischen Übersetzungsaktualisierungen geschützt.

Wenn Sie Schlüssel bewahren, initialisiert die CLI diese mit Quellwerten und überspringt sie bei zukünftigen Übersetzungsdurchläufen.

Einrichtung der Schlüsselbewahrung

Fügen Sie preservedKeys zu Ihrer Bucket-Konfiguration in i18n.json hinzu:

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

Das preservedKeys-Array verwendet die Schrägstrich-Notation (/), um verschachtelte Schlüssel anzugeben, und das Sternchen (*), um mehrere Schlüssel zu matchen.

Funktionsweise der Schlüsselbewahrung

Während der Übersetzungsverarbeitung führt die Lingo.dev CLI folgende Schritte aus:

1. Identifiziert bewahrte Schlüssel aus Ihrer Konfiguration
2. Schließt sie von der Übersetzung aus — bewahrte Schlüssel werden niemals an die Übersetzungs-Engine gesendet
3. Initialisiert fehlende Schlüssel — kopiert Quellwerte als Platzhalter für neue Zieldateien
4. Schützt vorhandene Werte — behält manuell übersetzte Inhalte unverändert bei

Beispiel-Workflow:

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

Mit Konfiguration für bewahrte Schlüssel:

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

Generierte spanische Übersetzung (erster Durchlauf):

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

Der welcome-Schlüssel wird übersetzt. Der legal-Abschnitt wird unverändert kopiert, um später manuell übersetzt zu werden.

Verschachtelte Schlüsselpfade

Verwenden Sie die Schrägstrich-Notation (/), um Schlüssel in beliebiger Tiefe zu bewahren:

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

Diese Notation funktioniert mit komplexen verschachtelten Strukturen:

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

Der Pfad legal/privacy/full bewahrt diesen spezifischen verschachtelten Schlüssel.

Schlüssel mit Punkten

Die Schrägstrich-Notation verarbeitet Schlüssel, die Punkte in ihren Namen enthalten:

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

Diese Schlüssel beibehalten mit:

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

Mehrere Bucket-Typen

Verschiedene Dateiformate können unterschiedliche beibehaltene Schlüssel haben:

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

Jeder Bucket-Typ verwaltet seine eigene Liste beibehaltener Schlüssel basierend auf der Inhaltsstruktur.

Schlüssel beibehalten vs. Schlüssel sperren

Schlüssel beibehalten und Schlüssel sperren dienen unterschiedlichen Zwecken:

Schlüssel beibehalten (preservedKeys):

• Schlüssel werden einmalig mit Quellwerten als Platzhalter initialisiert
• Vorhandene Zielwerte werden niemals durch die CLI überschrieben
• Wird für Inhalte verwendet, die manuelle Übersetzung oder rechtliche Prüfung erfordern

Schlüssel sperren (lockedKeys):

• Schlüssel werden in die Übersetzungsverarbeitung einbezogen, aber die Werte bleiben unverändert
• Gesperrte Schlüssel entsprechen immer exakt den Quellwerten
• Wird für technische Bezeichner, Komponentennamen oder Werte verwendet, die konsistent bleiben müssen

Vergleichsbeispiel:

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

Nach der manuellen Übersetzung von legal/privacy ins Spanische behalten nachfolgende Durchläufe die manuelle Übersetzung bei. Der Schlüssel system/component bleibt unabhängig vom Zieldateiinhalt immer auf Englisch.