Schnellstart

Die Kernstärke der Lingo.dev CLI liegt darin, Apps und Markdown-Inhalte effizient mit einem einzigen CLI-Befehl in Zielsprachen zu lokalisieren.

Diese Schnellstartanleitung geht davon aus, dass Sie entweder kurz davor stehen, Ihre App mehrsprachig zu machen, oder sie bereits für die Unterstützung von 2+ Sprachen konfiguriert haben. Daher ist die Anleitung so konzipiert, dass sie in weniger als 10 Minuten abgeschlossen werden kann, aber dennoch detailliert genug ist, um die internen Abläufe zu verstehen.

Nach Abschluss dieser Anleitung werden Sie:

1. App-Inhalte mit einer KI-Übersetzungs-Engine ins Spanische und Japanische lokalisieren;
2. Verstehen, wie Quelldateien, Zieldateien und die Konfiguration zusammenarbeiten;
3. Einen Lokalisierungs-Workflow einrichten, der Ihre App und Markdown-Inhalte auf Dutzende von Sprachen und Zehntausende von Wörtern skalieren kann.

Lassen Sie uns beginnen!

Voraussetzungen

Markdown

Markdown-Dateien sind strukturierte Dokumente, was bedeutet, dass keine vorherige Einrichtung erforderlich ist. Lingo.dev CLI verarbeitet .md-Dateien direkt und behält die Formatierung bei, während Inhalte lokalisiert werden, sodass Sie direkt mit Schritt 1 fortfahren können.

Anwendungen

Um eine App mehrsprachig zu machen, müssen Entwickler bei modernen Web- und mobilen Anwendungen zunächst eine Internationalisierungskonfiguration (i18n) einrichten.

Für diesen Schnellstart erstellen wir eine eigenständige JSON-Datei, um zu demonstrieren, wie Lingo.dev CLI Anwendungsinhalte lokalisiert.

Bei der Integration in Ihre eigentliche Anwendung folgen Sie unseren empfohlenen Framework-Anleitungen:

• React: react-intl
• Vue: vue-i18n
• Svelte: svelte-i18n
• Angular: ngx-translate
• iOS: Localizable.xcstrings
• Android: strings.xml

Schritt 1. Projekt initialisieren

Lingo.dev CLI verwendet die Standard-Konfigurationsdatei i18n.json, um Ihre Lokalisierungseinstellungen zu deklarieren. Um sie interaktiv zu erstellen, führen Sie aus:

npx lingo.dev@latest init

Es werden Ihnen Fragen zu Ihrem Projekt gestellt, dann wird eine i18n.json-Datei im Stammverzeichnis Ihres Projekts erstellt.

Die Datei sollte wie folgt aussehen:

{
  "locale": {
    "source": "en",
    "targets": ["es", "ja"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"]
    }
  }
}

Lassen Sie uns jedes Konfigurationselement entschlüsseln:

• locale.source — Die Sprache, in der Ihr Team schreibt. Diese Einstellung identifiziert, welche Dateien den maßgeblichen Inhalt enthalten. Der gesamte Lokalisierungsfluss geht von der Quelle zu den Zielen.

• locale.targets — Ein Array von ISO 639-1-Sprachcodes, die Ihre Zielmärkte repräsentieren. Jeder Code entspricht einer separaten Datei (oder einem Abschnitt innerhalb einer Datei, abhängig vom Format). Sie können mit einer oder zwei Sprachen beginnen und weitere hinzufügen, wenn Sie expandieren.

• buckets.json.include — Glob-ähnliche Muster, die der CLI mitteilen, wo Lokalisierungsdateien zu finden und zu erstellen sind. Das spezielle Token [locale] wird zu jedem Sprachcode erweitert. Mit dem Muster locales/[locale].json sucht die CLI nach locales/en.json als Quelle und generiert locales/es.json und locales/ja.json als Ziele. Sie können mehrere Muster angeben und sogar Formate innerhalb einer einzelnen Konfiguration mischen.

Fortgeschrittene Funktionen, die Sie entdecken werden, wenn Ihr Projekt wächst:

• Mehrere Buckets für verschiedene Dateitypen oder Abschnitte Ihrer App
• exclude-Muster, um bestimmte Dateien zu überspringen
• lockedKeys, um bestimmte Werte vor Übersetzung zu schützen

Erstellen der englischen Quelldatei

Für diesen Schnellstart erstellen wir eine Lokalisierungsdatei:

mkdir -p locales
echo '{"greeting":"Hello, world!","button.submit":"Submit"}' > locales/en.json

Dies erstellt ein locales-Verzeichnis und eine englische Quelldatei mit zwei Übersetzungsschlüsseln. Schlüssel wie greeting funktionieren für flache Strukturen, während Namensraum-Schlüssel wie button.submit bei der Organisation größerer Anwendungen helfen.

Verschachtelte Objekte werden ebenfalls unterstützt. Weitere Details zu verschiedenen Dateiformaten finden Sie in der restlichen Dokumentation.

Schritt 2. Authentifizierung

Die Lingo.dev CLI sendet Ihre Inhalte zur Lokalisierung an die KI-Übersetzungs-Engine, daher müssen wir uns zunächst authentifizieren.

Option 1. Direkter LLM-API-Zugriff

Die Lingo.dev CLI hilft Ihnen, LLM-Modelle wie OpenAI oder Anthropic für Lokalisierung und Übersetzung zu nutzen.

Das bedeutet, dass Ihnen pro verarbeitetem Token Kosten entstehen, Sie die Modellauswahl, System-Prompts und alle Modellparameter kontrollieren.

Um sich zu authentifizieren, erstellen Sie eine .env-Datei im Stammverzeichnis Ihres Projekts mit Ihrem API-Schlüssel:

# wenn Sie OpenAI verwenden

OPENAI_API_KEY=sk-...

# wenn Sie Anthropic verwenden

ANTHROPIC_API_KEY=sk-...

Alternativ können Sie anstelle von .env die Variable in Ihrer aktuellen Shell-Sitzung exportieren:

export ANTHROPIC_API_KEY=sk-ant-...

Möchten Sie Unterstützung für einen anderen Anbieter hinzufügen? Lingo.dev CLI ist Open Source und begrüßt Beiträge! Forken Sie das Repository und reichen Sie einen Pull Request ein: github.com/lingodotdev/lingo.dev.

Option 2. Lingo.dev Engine

Alternativ können Sie ein kostenloses Lingo.dev Engine-Konto erstellen und es als Ihre KI-Übersetzungs-Engine verwenden.

Sie bietet dynamische Modellauswahl, automatisches Routing zu verschiedenen Modellen für jedes Sprachpaar, automatische Modell-Fallbacks, Translation Memory, das frühere Übersetzungen berücksichtigt, und Glossar-Unterstützung für die domänenspezifische Terminologie Ihres Projekts. Es gibt sowohl kostenlose als auch kostenpflichtige Optionen, und der kostenlose Hobby-Tarif sollte für dieses Tutorial ausreichend sein.

Zur Authentifizierung führen Sie aus:

npx lingo.dev@latest login

Wichtiges Detail. Wenn Sie den Brave-Browser verwenden oder Ihre Browser-Erweiterungen den Authentifizierungsablauf blockieren, können Sie sich manuell authentifizieren, indem Sie eine LINGODOTDEV_API_TOKEN-Umgebungsvariable zu Ihrer .env-Datei hinzufügen:

LINGODOTDEV_API_TOKEN=...

Sie finden den Token in den Projekteinstellungen der Lingo.dev Engine.

Schritt 3. KI-Übersetzungsengine einrichten

Nachdem Sie authentifiziert sind, müssen Sie konfigurieren, welche KI-Übersetzungsengine verwendet werden soll.

Option 1. Direkter LLM-API-Zugriff

Um OpenAI zu verwenden, aktualisieren Sie Ihre i18n.json-Konfiguration, um den openai-Provider zu nutzen:

{
  "locale": {
    "source": "en",
    "targets": ["es", "ja"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"]
    }
  },
  "provider": {
    "id": "openai",
    "model": "gpt-4o-mini",
    "prompt": "Act as a professional software localization expert. Translate each key from {source} to {target}. Preserve ICU message format placeholders like {name} and {{count}}. Maintain Markdown formatting including links and code blocks. Match the tone and formality of the source text. Technical terms that are typically untranslated in the industry should remain in English."
  }
}

Sie können mit verschiedenen Prompts experimentieren, um das Lokalisierungsverhalten anzupassen, aber wir haben festgestellt, dass dieser ein guter Ausgangspunkt ist!

Die provider-Konfiguration steuert den direkten LLM-Zugriff:

• id — Entweder openai oder anthropic
• model — Die spezifische Modellversion, die verwendet werden soll. Beispiele: gpt-4o-mini, gpt-4o (OpenAI) oder claude-3-haiku, claude-3-sonnet (Anthropic).
• prompt — Ein System-Prompt, der das Übersetzungsverhalten steuert. Die Platzhalter {source} und {target} werden zur Laufzeit durch die tatsächlichen Sprachcodes ersetzt. Dieser Prompt bietet die Möglichkeit, Terminologie, Stil und domänenspezifische Regeln durchzusetzen.

Option 2. Lingo.dev Engine

Wenn Sie die Lingo.dev Engine als KI-Übersetzungsengine verwenden, können Sie den provider-Knoten vollständig weglassen.

Die Engine wählt automatisch Modelle und Prompts basierend auf der Forschung des Lingo.dev-Teams und den Einstellungen Ihrer Engine aus.

Ihre i18n.json-Konfiguration:

{
  "locale": {
    "source": "en",
    "targets": ["es", "ja"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"]
    }
  }
}

Hinweis: Bei Verwendung der Lingo.dev Engine lassen Sie den provider-Knoten vollständig weg. Die Engine wählt automatisch Modelle und Prompts aus.

Schritt 4. Übersetzen

Um Ihre App zu lokalisieren, führen Sie folgenden Befehl aus:

npx lingo.dev@latest i18n

Die CLI erstellt die Zieldateien und aktualisiert die i18n.lock-Datei, die Content-Fingerprints verfolgt. Dies gewährleistet inkrementelle Updates bei nachfolgenden Durchläufen.

Sie haben jetzt den Inhalt Ihrer App lokalisiert!

Nächste Schritte

Sie haben den grundlegenden Lokalisierungsworkflow abgeschlossen. Ihr Repository enthält jetzt lokalisierte Dateien, die wie jedes andere Code-Artefakt committet, überprüft und bereitgestellt werden können.

Von hier aus können Sie:

• Den Workflow automatisieren: CI/CD-Integration — Richten Sie eine CI/CD-Integration ein, um bei jedem Push zu lokalisieren und die Änderungen automatisch über Pull Requests oder direkte Commits in Ihr Repository zurückzuführen;
• Die internen Abläufe verstehen: Wie es funktioniert — Erfahren Sie mehr über die Algorithmen, Leistungsoptimierungen und architektonischen Entscheidungen.