Formate
Finde den passenden Datei-Handler, der deine Texte übersetzt und dabei die Struktur erhält, die deine Anwendung braucht.
Eine Sprachdatei enthält mehr als nur Wörter. Ihre Schlüssel verknüpfen Meldungen mit Code, ihre Platzhalter nehmen Werte aus der Anwendung auf, und ihre Struktur legt fest, wie ein Framework das Ergebnis lädt. Bei Dokumenten kommen Überschriften, Links, Beispiele und Metadaten hinzu. Bei der Dateiübersetzung muss sich die Sprache ändern, ohne dass diese Verbindungen verloren gehen.
Lingo.dev verwendet einen Format-Handler, um übersetzbare Texte auszuwählen und das Ergebnis wieder zusammenzusetzen. Entscheidend für die Wahl des Handlers ist, welche Funktion die Datei erfüllt. Ein Rails-Katalog und eine OpenAPI-Spezifikation können beide auf .yml enden. Jede Zeichenfolge darin zu übersetzen, würde jedoch jeweils andere Probleme verursachen: In einem Rails-Katalog muss sich der Sprach-Wurzelschlüssel ändern, während die Operationskennungen einer API unverändert bleiben müssen.
Finde dein Format #
| Quelle | Handler-Typ | Referenz |
|---|---|---|
| Verschachtelter JSON-Katalog | json | JSON |
| JSON mit Kontextkommentaren | jsonc | JSONC |
| YAML-Katalog | yaml | YAML |
| YAML mit einem Sprach-Wurzelschlüssel | yaml-root-key | YAML mit Sprach-Wurzelschlüssel |
| Statisches TypeScript-Sprachmodul | typescript | TypeScript |
| Statisches PHP-Spracharray | php | PHP |
| Markdown-Dokument | md | Markdown |
| Markdown mit JSX-Komponenten | mdx | MDX |
| Markdoc-Dokument | markdoc | Markdoc |
| OpenAPI-3.x-YAML | yaml-openapi | OpenAPI |
| Android-Ressourcen-XML | android | Android |
| Flutter Application Resource Bundle | flutter | Flutter ARB |
| Apple-Zeichenfolgentabelle | xcode-strings | Apple strings |
| Apple-plist für Pluralressourcen | xcode-stringsdict | Apple stringsdict |
| Mehrsprachiger Apple-Katalog | xcode-xcstrings | Apple-String-Kataloge |
| Gettext-PO-Katalog | po | Gettext |
| XLIFF-Austauschdokument | xliff | XLIFF |
| SubRip-Untertitel | srt | SubRip |
| Klartext, zeilenweise übersetzt | txt | Klartext |
| HTML-Dokument oder -Fragment | html | HTML |
| CSV-Tabelle mit einer Spalte pro Sprache | csv | CSV |
| Java-Properties-Ressourcenpaket | properties | Java-Properties |
| Ausgewählte Felder in Payload CMS | payload | Payload |
Die Referenzen beschreiben die etablierten Dateihandler und ihre Grenzen bei der Extraktion und Rekonstruktion. Die CLI und die GitHub App unterstützen die 22 oben aufgeführten konfigurierten Typen mit Ausnahme von Payload. HTML wird anhand von .html und .htm erkannt; die Ausgabe behält unveränderten Quelltext bei und setzt bei einem expliziten <html>-Element den Wert von lang auf die Zielsprache. Wähle in der Repository-Konfiguration ausdrücklich die gewünschte YAML-Variante oder das Android-Format aus. Wie Apple String Catalogs speichert CSV alle Sprachen in der Quelldatei. Der CLI-Schnellstart führt anhand einer Datei durch die Einrichtung und den Abruf; GitHub beschreibt den verwalteten Repository-Workflow.
Die aktuellen Anbieteranbindungen wählen Inhalte über ihre eigenen Integrationsverträge aus und schreiben sie darüber zurück.
Um strukturierte Daten direkt zu übersetzen, übermittle Inline-JSON. Wenn du Quelldateien hochladen und ihre Formate beibehalten möchtest, folge der Anleitung unter Dateidokumente. Beide Wege nutzen denselben Lebenszyklus für Übersetzungsaufträge.
Bewahre die Quellversion zusammen mit ihren Übersetzungen auf #
Die inkrementelle Dateiübersetzung vergleicht die aktuelle Quellversion mit einer früheren und verwendet die dazugehörige vorhandene Zielversion. So behalten unveränderte Meldungen ihre akzeptierte Formulierung, während neue oder geänderte Meldungen übersetzt werden.
Schlüssel machen diesen Vergleich sinnvoll: checkout.title und account.title können denselben englischen Text enthalten und trotzdem unterschiedliche Übersetzungen behalten. Auch Array-Positionen, Untertitelnummern, Zeilenpositionen in Klartextdateien und die Dokumentstruktur fließen in den Abgleich ein. Wenn du ein Element verschiebst oder ein übersetztes Dokument neu strukturierst, kann sich die Zuordnung ändern. Bewahre Zielversionen deshalb immer zusammen mit der Quellversion auf, aus der sie entstanden sind.
Die meisten Formate erzeugen für jede Zielsprache eine separate Datei. Apple-String-Kataloge führen die Sprachen stattdessen in der Quelldatei zusammen. Ein Payload-Artefakt oder ein String-Katalog kann bereits einige Zielwerte enthalten, während andere noch fehlen. Führe deshalb eine Prüfung der tatsächlichen Zieleinträge durch, statt nur darauf zu achten, ob eine Datei vorhanden ist.
Steuere Textauswahl und Ausgabe getrennt #
Text von der Übersetzung auszuschließen, kann Unterschiedliches bedeuten. Ein gesperrter Katalogwert wird aus der Quelle übernommen, ein beibehaltener Wert aus der vorhandenen Zielversion. Ein ignorierter Wert kann aus der Ausgabe verschwinden. Welche Steuerungsmöglichkeiten verfügbar sind, hängt vom Format und von der aufrufenden Schnittstelle ab.
Verwende CLI-Schlüsselbereiche für JSON/JSONC, YAML, YAML mit Sprach-Wurzelschlüssel, PHP und TypeScript. Bei einer Teilaktualisierung bleiben vorhandene Zielformulierungen außerhalb der Auswahl erhalten. Wie Einträge behandelt werden, die nur in der Quelle vorhanden sind, und wie mit Array-Positionen umgegangen wird, hängt jedoch vom Format ab. Sieh dir das gesamte Ergebnis mithilfe der jeweiligen Formatreferenz an.
Auch für Kontextmetadaten gelten spezifische Regeln. Ein @context-Kommentar in JSONC beschreibt den nächsten Zeichenfolgenwert. Ein @message.description in ARB beschreibt die zugehörige Meldung. In Gettext dient msgctxt dazu, Meldungen zu unterscheiden und Kontext bereitzustellen. Gewöhnliche Kommentare können bei der Rekonstruktion erhalten bleiben, ohne als Übersetzungsanweisungen zu dienen. Die React-Annotationen @src und @orphan gehören zum Workflow zur Katalogpflege von React.
Lade eine abgerufene Datei anschließend mit dem System, das sie verwendet. Kontrolliere neben der Bedeutung der Übersetzung auch die ausgewählte Sprache, Variablen, Pluralformen, Links und geschützten Daten. Die Anwendungsleitfäden zeigen dir die abschließenden Schritte für Webanwendungen, native Ressourcen und statische Inhalte.