Schlüsselsteuerung
Lege fest, ob ein Wert aus dem Quellinhalt, einem vorhandenen Ziel, einer Übersetzung oder den Sprachmetadaten stammt.
Manche Katalogwerte sollen in allen Sprachen identisch bleiben. Andere werden im Ziel manuell gepflegt. Mit der Schlüsselsteuerung legst du diese Entscheidungen ausdrücklich fest, damit ein Dateihandler, der diese Optionen unterstützt, sie beim Rekonstruieren der Ausgabe berücksichtigt.
Diese Optionen gelten für Dateieinträge in .lingo/config.json. Sie wählen weder Dateien aus noch fordern sie eine Aktualisierung der Schlüssel an; dafür sind die Übersetzungsbereiche zuständig.
| Steuerungsoption | Ausgabeverhalten |
|---|---|
lockedKeys | Den Quellwert ohne Übersetzung kopieren. |
preservedKeys | Den vorhandenen Zielwert beibehalten, sofern verfügbar. |
ignoredKeys | Ausgewählte Inhalte aus der Ausgabe eines Formats entfernen, das diese Option unterstützt. |
injectLocale | Die Zielsprache an eine ausgewählte Position schreiben. |
Jedem Wert eine Zuständigkeit zuweisen #
{
"pattern": "locales/en.json",
"lockedKeys": ["product.id"],
"preservedKeys": ["legal.notice"],
"ignoredKeys": ["internal.note"],
"injectLocale": { "enabled": true, "key": "meta.locale" }
}Hier stammt die Produkt-ID aus der Quelle, der vorhandene rechtliche Hinweis bleibt aus dem Ziel erhalten und die interne Notiz wird weggelassen. Die Sprachinjektion schreibt die Zielsprache an die Position meta.locale und erstellt bei Bedarf fehlende Objektcontainer. Für Positionen in Arrays gib ein vorhandenes Array an und wähle ein vorhandenes Element oder die Position unmittelbar nach dem Array-Ende aus. Pfade, die Lücken erzeugen oder über inkompatible Werte führen, schlagen fehl.
Die Beibehaltung kann keine manuelle Übersetzung erzeugen, wo noch keine vorhanden ist. Schon bei der normalen inkrementellen Verarbeitung werden vorhandene Zielinhalte verwendet, um Bearbeitungen an unveränderten Schlüsseln zu erhalten; preservedKeys bietet darüber hinaus gezielten Schutz. Eine geänderte Quelle oder ein umbenannter JSON-Schlüssel kann dennoch eine erneute Verarbeitung erfordern.
Pfade und überlappende Steuerungsoptionen #
Die Steuerungsoptionen für JSON/JSONC verwenden durch Punkte getrennte Namen und Indizes in eckigen Klammern, etwa checkout.submit oder items[0].title. Ein geschützter Pfad kann auch untergeordnete Elemente abdecken. Verwende eine JSONPath-Eigenschaft in Anführungszeichen, etwa $['checkout.submit'], wenn der Schlüsselname selbst einen Punkt enthält. lingo push liest auch Listen, die mit / für die frühere CLI geschrieben wurden: Jeder Name zwischen / wird als Ganzes behandelt. Damit entspricht checkout/submit dem Ausdruck checkout.submit, und common/error.message bezeichnet den Schlüssel error.message unter common. Prozentkodierte Namen wie legal/Terms%20of%20use werden dekodiert; ein Muster ohne / gilt als Punktpfad und wird nicht dekodiert. Schreibe einen einzelnen kodierten Namen daher als JSONPath, etwa $['Terms of use']. Da jedes Muster mit / auf diese Weise gelesen wird, braucht ein Schlüssel, dessen Name / enthält, ebenfalls JSONPath, etwa $.routes['/about'].title. Ein abschließendes *, wie in internal/*, deckt wie in der früheren CLI die Werte direkt unter internal ab, nicht aber dort verschachtelte Objekte oder Arrays. Die frühere CLI erfasste auch Schlüssel, die mit - oder . weitergehen, sodass legal/terms auch legal/terms-short abdeckte. Dieser Präfixabgleich entfällt; führe solche Schlüssel separat auf. Die GitHub App akzeptiert die Schreibweise mit Schrägstrichen nicht: Wenn die App dieselbe Konfiguration liest, schreibe diese Listen mit Punkten oder als JSONPath. Unter Bereiche wird diese Schreibweise beschrieben.
An derselben Position entfernt eine Ausschlussregel den Wert, auch einen durch Sprachinjektion eingefügten Wert. Die Sprachinjektion hat Vorrang vor Sperrung und Beibehaltung. Eine Sperrung hat Vorrang vor der Beibehaltung: Steht ein Schlüssel in beiden Listen, wird sein Quellwert verwendet. Wird ein übergeordnetes Element ausgeschlossen, werden auch seine untergeordneten Elemente entfernt. Weise jedem Wert möglichst nur eine Zuständigkeit zu und sieh dir die Ausgabe an, wenn sich Regeln innerhalb eines Objekts oder Arrays überschneiden.
Beim erzwungenen Ersetzen der gesamten Datei wird das an den Server gesendete Artefakt des aktuellen Ziels geleert. Ohne diesen Zielkontext kann eine Beibehaltungsregel frühere manuelle Formulierungen nicht erhalten. Bewahre vor dem erzwungenen Ersetzen eine Kopie auf, aus der du den bisherigen Stand wiederherstellen kannst.
Grenzen der Dateihandler #
JSON und JSONC unterstützen alle vier Steuerungsmöglichkeiten. TypeScript, PHP, YAML und YAML mit einer Sprache als Wurzelelement unterstützen das Sperren, Beibehalten und Ignorieren; stringsdict unterstützt das Sperren und Beibehalten. Java-Properties unterstützt das Sperren, Beibehalten und Ignorieren sowie den Schlüsselbereich. Dabei wird jedes Muster wie in der bisherigen CLI mit dem gesamten Schlüssel abgeglichen. CSV unterstützt keine der drei Schlüsselregeln: Die CLI und die GitHub App lehnen CSV-Einträge ab, in denen lockedKeys, preservedKeys oder ignoredKeys festgelegt ist. Wie die Ausgabe erfolgt, erfährst du in der Referenz zum Format für das gewählte Format.
Die kurze Pfadschreibweise unterstützt * für ganze Segmente, numerische Indizes und leere eckige Klammern. Platzhalter für Teile eines Segments werden abgelehnt. Mit lingo push akzeptieren die drei Listen für Schlüsselregeln auch die Schreibweise mit Schrägstrichen; die GitHub App und die Position für die Sprachinjektion akzeptieren sie nicht. Verwende JSONPath-Eigenschaften in Anführungszeichen, wenn der Name selbst Satzzeichen enthält; explizite $-Abfragen werden unverändert weitergegeben. Die Injektion erfordert genau eine Position. Bei aktivierter Injektion ist language der Standardschlüssel.