YAML mit Root-Keys - Lingo.dev CLI

Was ist YAML mit Root-Keys?

YAML mit Root-Keys ist ein Lokalisierungsformat, bei dem die Übersetzungen jeder Sprache unter einem Root-Level-Schlüssel organisiert sind, der nach dem Sprachcode benannt ist. Dieses Format ermöglicht die Speicherung mehrerer Sprachen in derselben Verzeichnisstruktur, während sie nach Sprachen organisiert bleiben.

Zum Beispiel:

en:
  navigation:
    home: "Home"
    about: "About Us"
    contact: "Contact"
  forms:
    title: "Contact Form"
    name_label: "Your Name"
    submit_button: "Send Message"

Was ist Lingo.dev CLI?

Lingo.dev CLI ist eine kostenlose, Open-Source-CLI zum Übersetzen von Apps und Inhalten mit KI. Sie wurde entwickelt, um traditionelle Übersetzungsmanagementsoftware zu ersetzen und sich gleichzeitig in bestehende Pipelines zu integrieren.

Um mehr zu erfahren, siehe Überblick.

Über diesen Leitfaden

Dieser Leitfaden erklärt, wie man YAML-Dateien mit Locale-Root-Keys mithilfe der Lingo.dev CLI übersetzt.

Sie lernen, wie man:

Ein Projekt von Grund auf erstellt
Eine Übersetzungspipeline konfiguriert
Übersetzungen mit KI generiert

Voraussetzungen

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

❯ node -v
v22.17.0

Schritt 1. Projekt einrichten

Erstellen Sie in Ihrem Projektverzeichnis 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 zu übersetzenden Sprachen und wo sich die lokalisierbaren Inhalte im Dateisystem befinden.

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

Schritt 2. Quellsprache konfigurieren

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

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

Die Quellsprache muss als BCP 47 Sprach-Tag angegeben werden.

Für die vollständige Liste der Sprachcodes, die Lingo.dev CLI unterstützt, siehe Unterstützte Sprachcodes.

Schritt 3. Konfigurieren der Zielsprachen

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

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

Schritt 4. Erstellen des Quellinhalts

Falls Sie es noch nicht getan haben, erstellen Sie eine oder mehrere YAML-Dateien mit Locale-Root-Keys, die den zu übersetzenden Inhalt enthalten. Diese Dateien müssen sich in einem Pfad befinden, der irgendwo die Quellsprache enthält (z.B. als Verzeichnisname wie en/ oder als Teil des Dateinamens wie messages.en.yml).

Schritt 5. Bucket erstellen

Fügen Sie in der Datei i18n.json ein "yaml-root-key"-Objekt zum buckets-Objekt hinzu:

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

Definieren Sie im "yaml-root-key"-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": {
    "yaml-root-key": {
      "include": ["./[locale]/example.yml"]
    }
  }
}
```
Diese Muster definieren, welche Dateien übersetzt werden sollen.

Die Muster selbst:
- müssen [locale] als Platzhalter für die konfigurierte Sprache enthalten
- können auf Dateipfade verweisen (z.B. "[locale]/translations.yml")
- können Sternchen als Wildcard-Platzhalter verwenden (z.B. "[locale]/*.yml")
Rekursive Glob-Muster (z.B. **/*.yml) werden nicht unterstützt.

Schritt 6. Konfigurieren eines LLM

Lingo.dev CLI verwendet große Sprachmodelle (LLMs), um Inhalte mit KI zu übersetzen. Um eines dieser Modelle zu nutzen, benötigen Sie einen API-Schlüssel von einem unterstützten Anbieter.

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

Registrieren Sie sich für ein Lingo.dev-Konto.
Führen Sie den folgenden Befehl aus:
```
npx lingo.dev@latest login
```
Dies öffnet Ihren Standard-Browser und fordert Sie zur Authentifizierung auf.
Folgen Sie den Anweisungen.

Schritt 7. Generieren der Übersetzungen

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

npx lingo.dev@latest run

Dieser Befehl:

Liest die i18n.json Datei.
Findet die Dateien, die übersetzt werden müssen.
Extrahiert den übersetzbaren Inhalt aus den Dateien.
Verwendet das konfigurierte LLM, um den extrahierten Inhalt zu übersetzen.
Schreibt den übersetzten Inhalt zurück in das Dateisystem.

Bei der ersten Generierung von Übersetzungen wird eine i18n.lock Datei erstellt. Diese Datei verfolgt, welche Inhalte bereits übersetzt wurden, und verhindert unnötige Neuübersetzungen bei nachfolgenden Ausführungen.

Beispiel

en/example.yml

en:
  navigation:
    home: "Home"
    about: "About Us"
    contact: "Contact"
    services: "Services"
  forms:
    title: "Contact Form"
    name_label: "Your Name"
    email_label: "Email Address"
    message_label: "Message"
    submit_button: "Send Message"
    success_message: "Thank you for your message!"

es/example.yml

es:
  navigation:
    home: "Inicio"
    about: "Sobre Nosotros"
    contact: "Contacto"
    services: "Servicios"
  forms:
    title: "Formulario de Contacto"
    name_label: "Su Nombre"
    email_label: "Dirección de Correo Electrónico"
    message_label: "Mensaje"
    submit_button: "Enviar Mensaje"
    success_message: "¡Gracias por su mensaje!"

i18n.json

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

i18n.lock

version: 1
checksums:
  1b0d7c9f07dcc31a978bc337763270ea: {}
  87b1c33c3f85415e0906ece6cfed17c5:
    navigation/home: 104a3db3b671c04e167eafbe21e57881
    navigation/about: 8f89131a66d4659be07cd5af2c7ea898
    navigation/contact: 9afa39bc47019ee6dec6c74b6273967c
    navigation/services: 8ea10b45b9abab2a3bfc3c07e1c9cdc6
    forms/title: ac85dea7c7f0bf1cd7d48cc1b4da3acc
    forms/name_label: 03c6ae7996d5841f743cd406b4eff72d
    forms/email_label: 0ee22bbbe989a0c61a18023407d12dc2
    forms/message_label: f2f72126bd244cfc534eab395e054362
    forms/submit_button: 487177489aafc9c0243c57ef3850a2d9
    forms/success_message: a0a7aa980dffa31d4d194af718a917b3