CSV
Übersetze eine CSV-Tabelle, die alle Sprachen in einer Datei zusammenfasst – mit einer eigenen Spalte pro Sprache und einer frei wählbaren Schlüsselspalte.
Eine CSV-Übersetzungstabelle enthält den Ausgangstext und alle Übersetzungen in einer Datei: eine Zeile pro Nachricht, eine Spalte pro Sprache. Der csv-Dateihandler füllt die Zellen der Zielsprachen in dieser Datei und schreibt das Ergebnis zurück an den Quellpfad. Dabei schreibt er nur in die Zellen der Zielsprachen und ergänzt eine Spalte, wenn für eine Sprache noch keine vorhanden ist, wie unter Welche Zeilen übersetzt werden beschrieben. Alle anderen Spalten, die Zeilenreihenfolge, Anführungszeichen und Zeilenenden bleiben unverändert. Eine UTF-8-Bytereihenfolgemarkierung am Dateianfang bleibt nicht erhalten: Die ausgegebene Datei beginnt ohne diese Markierung. Wenn eine Tabellenkalkulation UTF-8 anhand der Markierung erkennt, muss die Datei daher möglicherweise ausdrücklich als UTF-8 importiert werden.
Tabelle aufbauen #
Die erste Zeile, die weder leer ist noch ausschließlich aus Leerraumzeichen besteht, dient als Kopfzeile. Eine Spalte enthält den Schlüssel, der jede Zeile identifiziert, eine weitere den Ausgangstext. Jede Zielsprache hat eine eigene Spalte:
id,en,notes,de
checkout.title,Complete your order,Shown on the last step,Bestellung abschließen
checkout.pay,"Pay now, or later",,- Sprachspalten. Eine Spalte gehört zu einer Sprache, wenn ihre Überschrift mit dem Sprachcode übereinstimmt. Groß- und Kleinschreibung spielen dabei keine Rolle:
deundDEbezeichnen die deutsche Spalte,de-DEdagegen eine andere Sprache. Die Überschrift der Quellspalte entsprichtsourceLocaleaus deiner Konfiguration. - Schlüsselspalte. Standardmäßig gibt die erste Zelle der Kopfzeile den Namen der Schlüsselspalte an. Setze
keyColumnim Dateieintrag, um eine andere Spalte zu verwenden. Wenn der Ausgangstext als Schlüssel dient, kann die Quellspalte selbst die Schlüsselspalte sein. - Andere Spalten. Spalten, die weder als Schlüssel- noch als Sprachspalte dienen, etwa
notes, bleiben Byte für Byte erhalten und werden nie zur Übersetzung gesendet. - Syntax. Zellen werden durch Kommas getrennt. Enthält eine Zelle ein Komma, ein Anführungszeichen oder einen Zeilenumbruch, wird sie in doppelte Anführungszeichen eingeschlossen. Anführungszeichen innerhalb einer solchen Zelle werden doppelt geschrieben (
""). Dateien mit Semikolons oder Tabulatoren als Trennzeichen werden nicht unterstützt.
CSV-Übersetzung konfigurieren #
Eine CSV-Datei wird nur durch einen Dateieintrag ausgewählt, dessen Muster auf .csv endet – dann wird das Format automatisch erkannt – oder der "format": "csv" festlegt. Ein Eintrag mit "format": "csv" wählt ausschließlich .csv-Dateien aus. Ein weit gefasstes Muster wie data/**/* wählt ohne diese Formatangabe niemals eine CSV-Datei aus. So schreibt ein bestehender Eintrag nicht plötzlich unbeteiligte Datendateien um. Bei der Dateiendung wird zwischen Groß- und Kleinschreibung unterschieden: Eine Datei namens strings.CSV wird nicht übersetzt. Benenne sie daher in strings.csv um.
{
"sourceLocale": "en",
"targetLocales": ["de", "fr"],
"files": [{ "pattern": "i18n/strings.csv", "keyColumn": "id" }]
}Die Datei dient für jede Sprache selbst als Zieldatei. Deshalb wird targetPath für dieses Format abgelehnt. CSV-Zeilen werden nicht mit den Schlüsseloptionen abgeglichen, daher werden auch lockedKeys, preservedKeys und ignoredKeys abgelehnt. Dieselbe Konfiguration funktioniert sowohl in der CLI als auch in der GitHub App.
Welche Zeilen übersetzt werden #
| Zeile | Ergebnis |
|---|---|
| Schlüssel und Ausgangstext | Wird dort übersetzt, wo die jeweilige Sprachzelle leer oder veraltet ist. |
| Schlüssel, leere Quellzelle | Bleibt unverändert; die Sprachzellen werden nicht geändert. |
| Ausgangstext, Schlüsselzelle leer oder nur mit Leerzeichen | Bleibt unverändert und wird nicht übersetzt. Vergib einen Schlüssel, um die Zeile zu übersetzen. |
| Leerer Schlüssel und leere Quellzelle oder eine Leerzeile | Bleibt unverändert, auch wenn die Zeile nur Leerzeichen enthält. |
Eine Sprachzelle, die nur Leerzeichen enthält, gilt als leer. Eine gefüllte Zelle wird wiederverwendet, solange der Ausgangstext ihrer Zeile seit dem letzten Push unverändert ist. Ändert sich der Ausgangstext einer Zeile, wird jede Sprachzelle dieser Zeile erneut übersetzt. Bei einer seit dem letzten Push hinzugefügten Zeile bleiben gefüllte Zellen erhalten; nur leere Zellen werden übersetzt. Eine Zeile mit geändertem Schlüssel gilt als neu hinzugefügt. Gefüllte Zellen bleiben auch in folgenden Fällen erhalten: beim ersten Push der Datei, mit CLI --force, bei einem GitHub App-Befehl, der Dateien ohne --force angibt, und wenn die zuvor gepushte Datei keine eindeutige Quell- oder Schlüsselspalte zum Vergleich enthält, etwa weil eine davon umbenannt wurde. Ein GitHub App-Befehl mit --force übersetzt jede Zeile der Datei erneut.
Die folgenden Ausgangstexte werden kopiert statt übersetzt: Texte, die nur aus den ASCII-Ziffern 0 bis 9 bestehen, etwa 100; eine URL, die mit // beginnt oder deren Schema aus Buchstaben, Ziffern oder Unterstrichen gefolgt von :// besteht und deren Adresse nach // mit localhost beginnt oder mindestens ein Zeichen, einen Punkt und mindestens zwei weitere Zeichen enthält, etwa https://lingo.dev/docs; eine 22 Zeichen lange ID, die nur aus Buchstaben und Ziffern besteht und mindestens einen Großbuchstaben, einen Kleinbuchstaben und eine Ziffer enthält; sowie ein Datum oder eine Kombination aus Datum und Uhrzeit im ISO-8601-Format, etwa 2024-01-15 oder 2024-01-15T10:00:00Z. Der Ausgangstext wird in alle Zielsprachenzellen derselben Zeile übernommen und ersetzt dabei den jeweiligen Zellinhalt. Die Zeile wird weder zur Übersetzung gesendet noch in Rechnung gestellt. Andere Werte wie 1.5, 100%, eine E-Mail-Adresse oder ein Datum in einem anderen Format, etwa 15.01.2024, werden übersetzt. Ebenfalls übersetzt werden mailto:- und tel:-Links, URLs, deren Schema andere Zeichen enthält, etwa git+ssh://, sowie URLs, deren Adresse nicht mit localhost beginnt und keinen solchen Punkt enthält, etwa https://intranet oder https://a.b.
Fehlt die Spalte für eine Zielsprache, wird sie am Ende der Kopfzeile ergänzt. Mehrere neue Spalten werden nach ihren Sprachcodes alphabetisch angeordnet. Anschließend wird jede Zeile mit leeren Zellen aufgefüllt, damit alle Zeilen gleich viele Zellen haben. Zeilen werden niemals umgeordnet, hinzugefügt oder entfernt.
Fehler #
In den folgenden Fällen schlägt die Verarbeitung der Datei fehl, bevor etwas übersetzt oder abgerechnet wird. Die Fehlermeldung nennt das jeweilige Problem:
- das konfigurierte
keyColumnfehlt in der Kopfzeile oder die erste Zelle der Kopfzeile ist leer und es wurde keinkeyColumnfestgelegt; - zwei Zeilen haben denselben Schlüssel, wodurch ihre Übersetzungen in den falschen Zeilen landen würden;
- die Kopfzeile enthält keine Spalte für die Ausgangssprache;
- die Schlüsselspalte ist zugleich die Spalte einer Zielsprache;
- die Kopfzeile nennt das konfigurierte
keyColumn, die Ausgangssprache oder eine Zielsprache mehr als einmal; - eine Zeile enthält mehr Zellen als die Kopfzeile;
- eine in Anführungszeichen eingeschlossene Zelle wird nicht geschlossen;
- in derselben Zelle folgt Text nach einem schließenden Anführungszeichen.
Korrigiere die Datei und führe erneut einen Push aus. Die CLI zeigt die Meldung einmal unter der Datei an, nicht einmal pro Sprache. Schlägt der gesamte Durchlauf fehl, wird die Meldung in der abschließenden Run failed:-Zeile wiederholt. Die GitHub App zeigt sie im Check-Lauf an.
Eine vorhandene Übersetzung korrigieren #
Um den Wortlaut gezielt zu ändern, bearbeite die Zelle. Um eine einzelne Übersetzung neu zu erzeugen, leere die betreffende Zelle, lasse den Rest der Zeile unverändert und führe einen einfachen Push aus:
lingo push --waitCLI --force verwendet gefüllte Zellen wieder, genau wie bei Apple String Catalogs. --key grenzt eine CSV-Datei nicht ein: Die CLI bricht den Push mit einem Fehler ab, und die GitHub App überspringt die Datei. CLI purge überspringt die Datei, weil Quelle und Ausgabe denselben Pfad verwenden. Führe vor dem Commit eine Prüfung des gesamten Datei-Diffs durch.