Zur aktuellen CLI migrieren

Ersetze alte Buckets und Quelltext-Fingerprints und behalte dabei akzeptierte Übersetzungen und eine funktionierende Anwendung bei.

Die aktuelle @lingo.dev/cli arbeitet mit serverseitiger Push/Pull-Verarbeitung und .lingo als Projektzustand. Das ältere Paket lingo.dev nutzt lokale Bucket-Verarbeitung, i18n.json und i18n.lock. Bei der Migration geht es darum, das Verhalten zu erhalten, das dein Projekt braucht – nicht nur einen Befehl umzubenennen.

Einen funktionierenden Ausgangsstand sichern #

Dokumentiere die installierte Version und sichere Quelldateien, akzeptierte Zieldateien, Konfiguration und das alte Lockfile in der Versionsverwaltung. Stelle sicher, dass die Anwendung diese Zieldateien lädt. Behalte Router, Provider, Sprachumschalter und Kataloglader deiner bestehenden Lokalisierungslösung bei, bis ein klar abgegrenzter Ersatz funktioniert.

Dokumentiere die Framework- und Laufzeitversionen sowie die erforderlichen Quell-, Ziel- und Standardsprachen. Teste repräsentative Routen mit Sprachpräfix, die anfängliche Spracherkennung, das Fallback-Verhalten und den Sprachwechsel. Halte diese Anwendungstests von der Migration der Dateiübersetzung getrennt.

Die Dateiauswahl neu aufbauen #

Erstelle .lingo/config.json mit Quell- und Zielsprachen sowie expliziten Dateieinträgen. Verknüpfe anschließend die Organisation, für die du berechtigt bist, und deine Lokalisierungs-Engine. Alte Buckets und Fingerprints lassen sich nicht durch bloßes Umbenennen in dieses Schema übertragen.

Die aktuelle CLI-Konfiguration unterstützt 22 Formate, darunter HTML (.html und .htm), Klartext (.txt, eine Einheit pro Zeile wie in v0), CSV-Tabellen mit einer Spalte pro Sprache in einer einzigen Datei sowie Java-.properties-Dateien (eine Einheit pro Schlüssel wie in v0, wobei lockedKeys, preservedKeys und ignoredKeys wie in v0 abgeglichen werden und lockedPatterns in RE2-Syntax angegeben wird, die weder Lookaround noch Rückreferenzen unterstützt). Gleiche eine csv-Bucket-Datei aus v0 mit dem CSV-Layout ab, bevor du sie verschiebst. Gleiche die Pfade eines properties-Buckets aus v0 mit Java-Properties ab: Aus einem [locale]-Dateinamen wie messages_[locale].properties wird ein Quellmuster wie messages_en.properties. CSV-pro-Sprache, MJML und andere ausschließlich im alten System unterstützte Buckets benötigen eine validierte Konvertierung oder einen anderen Übersetzungsweg. Unter Konfiguration findest du die genauen Enum-Werte, Abgleichsmuster und Ausgabevorlagen. Die v0-Einstellungen für Modell, Prompt und Basis-URL bei direkter Anbieteranbindung gehören nicht in dieses Projektschema.

Sieh dir eine ausgewählte Quelldatei und die daraus abgeleiteten Zieldateipfade an, bevor du die Konfiguration erweiterst. Verwende für Props aus der Markdown-Familie translateComponentProps.

Übersetzungen übernehmen und aktualisieren #

Die aktuelle Planung für begrenzte Bereiche und das Bootstrap-Verfahren ermöglichen die Übernahme vorhandener Zieldateien. Kontrolliere repräsentative Dateien und manuelle Änderungen, bevor du diesen Ausgangsstand festlegst: Das bloße Vorhandensein einer Datei sagt nichts darüber aus, ob ihre Werte dem neuesten Quelltext entsprechen.

Backfill ergänzt fehlende reguläre Dateien, während v0 normalerweise fehlende Schlüssel in bestehenden Katalogen ergänzt. Nutze für diese späteren Schritte die aktuellen inkrementellen Quelltextaktualisierungen oder die unterstützte Schlüsselaktualisierung. Ein umbenannter JSON-Schlüssel wird als neuer Pfad verarbeitet, selbst wenn sein Text mit dem eines alten Schlüssels übereinstimmt. Verlasse dich nicht darauf, dass Übersetzungen bei Umbenennungen wie in v0 anhand von Inhalts-Fingerprints wiederverwendet werden.

Änderungen an Zieltexten mit unveränderten Schlüsseln können bei inkrementellen Durchläufen erhalten bleiben. Explizite Regeln zum Beibehalten von Schlüsseln erlauben eine separate Entscheidung darüber, wer diese Inhalte verwaltet. Bei Formaten mit separaten Dateien entfernt ein erzwungener Durchlauf für die gesamte Datei den Kontext der aktuellen Zieldatei und kann akzeptierte Formulierungen ersetzen. Er ist daher keine Abkürzung zur Übernahme bestehender Übersetzungen.

Den ersten Durchlauf mit der aktuellen CLI abschließen #

Folge dem aktuellen Schnellstart bis zum Backfill und zum Abruf der Dateien. Ein einfacher erster Push ohne Ausgangsstand speichert die Quellbytes, statt erste Übersetzungen anzufordern. Warte oder führe einen Pull aus, bevor du den Datei-Workflow als abgeschlossen betrachtest.

Erstelle einen gemeinsamen Commit mit den akzeptierten Quell- und Zieldateien, der Konfiguration und dem aktuellen Lockfile. Der Verweis auf den letzten Lauf bleibt lokal im Home-Verzeichnis und wird nicht über Git übertragen. Ein anschließender Pull vergleicht die Hashes; ein Commit, der nur die abweichende Änderung enthält, löst diesen Konflikt nicht. lingo check ersetzt die bisherige Frozen-Lock-Schranke auf Dateiebene: Der Befehl schlägt fehl, wenn sich eine Quelldatei seit .lingo/lock.json geändert hat oder eine Zieldatei fehlt. Ein fehlendes Lockfile legt er niemals an. Ohne ein im Commit enthaltenes Lockfile kann er Änderungen an Quelldateien nicht erkennen und kontrolliert lediglich, ob die Zieldateien vorhanden sind.

React-Migration #

Der aktuelle React-Workflow extrahiert Aufrufe mit literalen Quelltext- und Kontextangaben in JSONC und Deklarationen, übersetzt ausgewählte Kataloge und lädt anschließend zur Laufzeit eine Zeichenfolgen-Zuordnung. Stelle bei einer Komponente sicher, dass Fallback-Verhalten, Variablen, Sprachwechsel und akzeptierte Formulierungen stimmen, bevor du die Änderung ausweitest.

Nutze Bestehende React-Nachrichten migrieren und React für die paketspezifischen Schritte. Das mitgelieferte lingo guide migrate spiegelt die installierte Version wider; daraus ergibt sich keine Funktionsgleichheit mit jeder früher generierten Konfiguration.