CSV pro Gebietsschema

KI-Übersetzung für CSV-Dateien mit separaten Dateien pro Gebietsschema mithilfe der Lingo.dev CLI

Was ist CSV pro Gebietsschema?

CSV pro Gebietsschema ist ein Übersetzungsansatz, bei dem jedes Gebietsschema eine eigene separate CSV-Datei hat, anstatt alle Gebietsschemata in einer einzigen CSV-Datei mit mehreren Spalten zu speichern. Dieses Format ist nützlich, wenn Sie strukturierte Daten mit mehreren Spalten haben (wie Produktkataloge, Benutzerdaten oder Content-Management-Systeme), bei denen jede Zeile einen Datensatz und Spalten verschiedene Felder darstellen.

Zum Beispiel:

id,name,description,created,enabled,sort
1,Welcome,Welcome to our application,2024-01-01,true,1
2,Save,Save your changes,2024-01-01,true,2
3,Error,An error occurred,2024-01-01,true,3

Im Gegensatz zum Standard-CSV-Bucket, der alle Gebietsschemata in einer Datei mit Spalten wie KEY,en,es speichert, verwaltet der csv-per-locale-Bucket separate Dateien für jedes Gebietsschema und bewahrt dabei die ursprüngliche CSV-Struktur mit allen Spalten.

Was ist die Lingo.dev CLI?

Die Lingo.dev CLI ist eine kostenlose Open-Source-CLI zur Übersetzung von Apps und Inhalten mit KI. Sie wurde entwickelt, um herkömmliche Translation-Management-Software zu ersetzen und sich gleichzeitig in bestehende Pipelines zu integrieren.

Weitere Informationen finden Sie unter Übersicht.

Über diesen Leitfaden

Dieser Leitfaden erklärt, wie Sie CSV-Dateien mithilfe des csv-per-locale-Buckets mit der Lingo.dev CLI übersetzen.

Sie lernen Folgendes:

  • Ein Projekt von Grund auf erstellen
  • Eine Übersetzungspipeline mit separaten CSV-Dateien pro Gebietsschema konfigurieren
  • Übersetzungen mit KI generieren
  • Gesperrte und ignorierte Schlüssel verwenden

Voraussetzungen

Um die Lingo.dev CLI zu verwenden, stellen Sie sicher, dass Node.js v18+ installiert ist:

❯ node -v
v22.17.0

Schritt 1. Ein Projekt einrichten

Erstellen Sie im Verzeichnis Ihres Projekts eine i18n.json-Datei:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {}
}

Diese Datei definiert das Verhalten der Übersetzungspipeline, einschließlich der Sprachen, zwischen denen übersetzt werden soll, und wo die lokalisierbaren Inhalte im Dateisystem vorhanden sind.

Um mehr über die verfügbaren Eigenschaften zu erfahren, siehe i18n.json.

Schritt 2. Quell-Locale konfigurieren

Die Quell-Locale ist die ursprüngliche Sprache und Region, in der Ihr Inhalt verfasst wurde. Um die Quell-Locale zu konfigurieren, setzen Sie die Eigenschaft locale.source in der Datei i18n.json:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {}
}

Die Quell-Locale muss als BCP 47 Language Tag angegeben werden.

Die vollständige Liste der Locale-Codes, die von Lingo.dev CLI unterstützt werden, finden Sie unter Unterstützte Locale-Codes.

Schritt 3. Ziel-Locales konfigurieren

Die Ziel-Locales sind die Sprachen und Regionen, in die Sie Ihren Inhalt übersetzen möchten. Um die Ziel-Locales zu konfigurieren, setzen Sie die Eigenschaft locale.targets in der Datei i18n.json:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {}
}

Schritt 4. Quellinhalt erstellen

Falls noch nicht geschehen, erstellen Sie eine CSV-Datei für Ihre Quell-Locale. Die Datei sollte Folgendes enthalten:

  • Eine Kopfzeile mit Spaltennamen
  • Eine oder mehrere Datenzeilen
  • Beliebige benötigte Spalten (nicht auf bestimmte Spaltennamen beschränkt)

Die CSV-Datei muss sich an einem Pfad befinden, der die Quell-Locale irgendwo im Pfad enthält (z. B. als Verzeichnisname wie en/ oder als Teil des Dateinamens wie data.en.csv).

Hinweis: Im Gegensatz zum Standard-CSV-Bucket benötigen Sie keine "KEY"-Spalte oder eine Spalte, die der Quell-Locale entspricht. Der csv-per-locale-Bucket behandelt jede Zeile als Datensatz und übersetzt den gesamten Textinhalt in der CSV-Datei, während die Struktur erhalten bleibt.

Schritt 5. Bucket erstellen

  1. Fügen Sie in der Datei i18n.json ein "csv-per-locale"-Objekt zum buckets-Objekt hinzu:

    {
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "csv-per-locale": {}
  }
}

  2. Definieren Sie im "csv-per-locale"-Objekt ein Array mit einem oder mehreren include-Mustern:

    {
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "csv-per-locale": {
      "include": ["./[locale]/example.csv"]
    }
  }
}

    Diese Muster definieren, welche Dateien übersetzt werden sollen.

    Die Muster selbst:

    • müssen [locale] als Platzhalter für die konfigurierte Locale enthalten
    • können auf Dateipfade verweisen (z. B. "[locale]/data.csv")
    • können Sternchen als Wildcard-Platzhalter verwenden (z. B. "[locale]/*.csv")

    Rekursive Glob-Muster (z. B. **/*.csv) werden nicht unterstützt.

  3. Optional können Sie lockedKeys und ignoredKeys konfigurieren:

    {
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "csv-per-locale": {
      "include": ["./[locale]/example.csv"],
      "lockedKeys": ["locked_key_1"],
      "ignoredKeys": ["ignored_key_1"]
    }
  }
}
    • lockedKeys: Schlüssel (Spaltenwerte in der ersten Spalte, typischerweise eine ID), die nicht übersetzt werden sollen
    • ignoredKeys: Schlüssel, die nicht in den Ziel-Locale-Dateien erscheinen sollen

Schritt 6. LLM konfigurieren

Die Lingo.dev CLI verwendet Large Language Models (LLMs), um Inhalte mit KI zu übersetzen. Um eines dieser Modelle zu verwenden, benötigen Sie einen API-Schlüssel von einem unterstützten Anbieter.

Um so schnell wie möglich loszulegen, empfehlen wir die Verwendung der Lingo.dev Engine – unserer eigenen, gehosteten Plattform, die 10.000 Token kostenlose monatliche Nutzung bietet:

  1. Registrieren Sie sich für ein Lingo.dev-Konto.

  2. Führen Sie den folgenden Befehl aus:

    npx lingo.dev@latest login

    Dadurch wird Ihr Standard-Browser geöffnet und Sie werden zur Authentifizierung aufgefordert.

  3. Folgen Sie den Anweisungen.

Schritt 7. Übersetzungen generieren

Führen Sie im Verzeichnis, das die Datei i18n.json enthält, den folgenden Befehl aus:

npx lingo.dev@latest run

Dieser Befehl:

  1. Liest die i18n.json-Datei.
  2. Findet die Dateien, die übersetzt werden müssen.
  3. Extrahiert den übersetzbaren Inhalt aus den CSV-Dateien.
  4. Verwendet das konfigurierte LLM, um den extrahierten Inhalt zu übersetzen.
  5. Schreibt den übersetzten Inhalt zurück in separate CSV-Dateien für jede Zielsprache.

Beim ersten Generieren von Übersetzungen wird eine i18n.lock-Datei erstellt. Diese Datei verfolgt, welcher Inhalt übersetzt wurde, und verhindert unnötige erneute Übersetzungen bei nachfolgenden Durchläufen.

Beispiel

en/example.csv (vor der Übersetzung)

id,name,description,created,enabled,sort
1,Welcome,Welcome to our application,2024-01-01,true,1
2,Save,Save your changes,2024-01-01,true,2
3,Error,An error occurred,2024-01-01,true,3
4,Success,Operation completed successfully,2024-01-01,true,4
5,Loading,Please wait while we load your data,2024-01-01,true,5

es/example.csv (nach der Übersetzung)

id,name,description,created,enabled,sort
1,Bienvenida,Bienvenido a nuestra aplicación,2024-01-01,true,1
2,Guardar,Guarda tus cambios,2024-01-01,true,2
3,Error,Ha ocurrido un error,2024-01-01,true,3
4,Éxito,Operación completada con éxito,2024-01-01,true,4
5,Cargando,Por favor espera mientras cargamos tus datos,2024-01-01,true,5

i18n.json

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "csv-per-locale": {
      "include": ["./[locale]/example.csv"],
      "lockedKeys": ["locked_key_1"],
      "ignoredKeys": ["ignored_key_1"]
    }
  }
}

i18n.lock

version: 1
checksums:
  e8b273672f895de0944f0a2317670d7c:
    0/name: 1308168cca4fa5d8d7a0cf24e55e93fc
    0/description: 8de4bc8832b11b380bc4cbcedc16e48b
    1/name: f7a2929f33bc420195e59ac5a8bcd454
    1/description: 8de4bc8832b11b380bc4cbcedc16e48b
    2/name: d3d99b147cc363dc6db8a48e8a13d4c1
    2/description: 7cd986af1fe5e89abe7ecffba5413110

Unterschiede zum CSV-Bucket

Der csv-per-locale-Bucket unterscheidet sich in mehreren Punkten vom Standard-csv-Bucket:

  • Dateistruktur: csv-per-locale verwendet separate Dateien für jede Sprache (z. B. en/example.csv, es/example.csv), während csv eine einzelne Datei mit mehreren Spalten verwendet (z. B. KEY,en,es).

  • Spaltenanforderungen: csv-per-locale benötigt keine "KEY"-Spalte oder nach Sprachen benannte Spalten. Sie können jede Spaltenstruktur verwenden, die zu Ihren Daten passt.

  • Anwendungsfälle: csv-per-locale ist ideal für strukturierte Daten wie Produktkataloge, Content-Management-Systeme oder Datenbanken, bei denen jede Zeile einen Datensatz mit mehreren Feldern darstellt. Der Standard-csv-Bucket eignet sich besser für einfache Schlüssel-Wert-Übersetzungstabellen.

  • Dateiänderungen: Beide Buckets ändern Dateien direkt, aber csv-per-locale erstellt separate Dateien für jede Sprache, während csv neue Spalten zur vorhandenen Datei hinzufügt.