Lingo.dev GitLab-Integration

Die Lingo.dev GitLab CI/CD-Integration ist eine sichere, quelloffene CI/CD-Integration, die automatisch neue Inhalte lokalisiert und verhindert, dass unvollständige Übersetzungen in die Produktionsumgebung gelangen. Sie erstellt Merge-Requests oder Commits direkt in Ihren Branch, abhängig von den Workflow-Anforderungen Ihres Teams.

Sie implementiert auch eine automatische Konfliktlösung durch Rebasing, sodass Ihre Übersetzungen ohne manuelle Eingriffe mit Ihrem Code synchronisiert bleiben.

Die Integration unterstützt mehrere Workflow-Szenarien:

1. Direkte Commits in Branches, wenn Inhaltsänderungen gepusht werden
2. Merge-Requests für Branches zur Aktualisierung von Übersetzungen

Nach Abschluss dieser Anleitung werden Sie:

1. Eine automatisierte Lokalisierung einrichten, die durch Code-Pushes ausgelöst wird;
2. Eine sichere Authentifizierung über Repository-Variablen konfigurieren;
3. Zwischen direkten Commits oder Merge-Request-Workflows wählen;
4. Verstehen, wie kontinuierliche Lokalisierung in Ihren bestehenden Prozess passt.

Lassen Sie uns beginnen!

Voraussetzungen

Repository-Einrichtung

Dein Repository muss die Lingo.dev CLI mit einer gültigen i18n.json-Datei konfiguriert haben. Wenn du dies noch nicht eingerichtet hast, absolviere zuerst den CLI-Schnellstart.

Schritt 1. Authentifizierungseinrichtung

Die Lingo.dev GitLab-Integration benötigt Zugriff auf Ihre Übersetzungs-Engine und Ihr Repository. Die Authentifizierung erfolgt über Repository-Variablen, die Ihre Anmeldedaten sicher aufbewahren.

Hinzufügen Ihres API-Schlüssels

Navigieren Sie zu Ihren Repository-Einstellungen → CI/CD → Variablen und fügen Sie dann Ihre Übersetzungs-Engine-Anmeldedaten hinzu:

Für Nutzer der rohen LLM-API:

• Variablenname: OPENAI_API_KEY oder ANTHROPIC_API_KEY
• Variablenwert: Ihr API-Schlüssel vom jeweiligen Anbieter

Für Lingo.dev Engine-Nutzer:

• Variablenname: LINGODOTDEV_API_KEY
• Variablenwert: Ihr Projekt-API-Schlüssel von lingo.dev/app

GitLab-Zugriffstoken hinzufügen

Erstellen Sie ein benutzerdefiniertes Zugriffstoken für Repository-Operationen:

1. Gehen Sie zu Einstellungen → Zugriffstoken → Neues Token hinzufügen
2. Gewähren Sie diese Berechtigungen:
   • api
   • read_repository
   • write_repository
3. Fügen Sie das Token als Repository-Variable hinzu:
   • Variablenname: GL_TOKEN
   • Variablenwert: Ihr GitLab-Zugriffstoken

Wichtig: Das Standard-CI-Job-Token ist nicht ausreichend. Sie müssen ein benutzerdefiniertes Zugriffstoken erstellen, da dem Standardtoken die notwendigen Berechtigungen für Git-Operationen fehlen.

Hinweis: Für geschützte Branches stellen Sie sicher, dass Ihre Variablen ebenfalls als geschützt markiert sind. Ungeschützte Variablen sind in Pipelines für geschützte Branches nicht zugänglich.

Schritt 2. Workflow erstellen

Erstellen oder aktualisieren Sie Ihre .gitlab-ci.yml-Datei mit dieser grundlegenden Konfiguration:

lingodotdev:
  image: lingodotdev/ci-action:latest
  script:
    - echo "Done"

Diese Konfiguration verwendet das neueste Docker-Image und führt die Übersetzungs-Engine automatisch aus.

Erforderliche Berechtigungen

GitLab CI/CD benötigt Zugriff auf Repository-Variablen und Git-Operationen:

Repository-Variablen:

• LINGODOTDEV_API_KEY — Erforderlich für Lingo.dev Engine-Benutzer
• OPENAI_API_KEY oder ANTHROPIC_API_KEY — Erforderlich für Benutzer der reinen LLM-API
• GL_TOKEN — Erforderlich für Git-Push-Operationen und Merge-Request-Erstellung

Zugriffstoken-Bereiche:

• api — Erstellen und Verwalten von Merge-Requests
• read_repository — Zugriff auf Repository-Inhalte
• write_repository — Commits pushen und Branches erstellen

Diese Berechtigungen ermöglichen der Integration, Ihre Inhalte zu lesen, Übersetzungen zu generieren und Ihr Repository mit den lokalisierten Inhalten zu aktualisieren.

Schritt 3. Workflow-Modus auswählen

Lingo.dev GitLab-Integration unterstützt zwei Betriebsmodi, abhängig von den Code-Review-Anforderungen Ihres Teams.

Direkter Commit-Modus (Standard)

Die Integration committet Übersetzungen direkt in Ihren Branch:

lingodotdev:
  image: lingodotdev/ci-action:latest
  script:
    - echo "Done"

Dieser Modus eignet sich am besten für:

• Einzelentwickler oder kleine Teams
• Feature-Branches, die vor dem Mergen überprüft werden
• Projekte, bei denen Übersetzungsaktualisierungen keine separate Überprüfung erfordern

Merge-Request-Modus

Die Integration erstellt Merge-Requests für Übersetzungsaktualisierungen:

lingodotdev:
  image: lingodotdev/ci-action:latest
  variables:
    LINGODOTDEV_PULL_REQUEST: "true"
  script:
    - echo "Done"

Erforderliche Einrichtung für den Merge-Request-Modus

Repository-Variablen: Sowohl LINGODOTDEV_API_KEY als auch GL_TOKEN müssen als Repository-Variablen konfiguriert werden.

Anforderungen an das Zugriffstoken: Ihr GL_TOKEN muss den Bereich api enthalten, um Merge-Requests zu erstellen und zu verwalten.

Dieser Modus eignet sich am besten für:

• Teams mit strengen Code-Review-Anforderungen
• Projekte, bei denen Übersetzungsänderungen eine separate Genehmigung benötigen
• Workflows, die eine explizite Überprüfung aller Änderungen erfordern

Schritt 4. Workflow-Szenarien

Die Lingo.dev GitLab-Integration passt sich verschiedenen Entwicklungs-Workflows an. Das Verständnis dieser Szenarien hilft Ihnen, die richtige Konfiguration für Ihr Team auszuwählen.

Szenario 1: Feature-Branch-Updates (Direkte Commits)

Auslöser: Push auf Feature-Branches Aktion: Committet Übersetzungsaktualisierungen direkt in den Feature-Branch

lingodotdev:
  image: lingodotdev/ci-action:latest
  script:
    - echo "Done"
  rules:
    - if: $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH = /^feat/

Ablauf: Inhaltsänderungen werden in den Feature-Branch gepusht → Integration committet Übersetzungen in denselben Branch

Dies hält Übersetzungsaktualisierungen innerhalb des Feature-Branches und stellt sicher, dass Übersetzungen zusammen mit den ursprünglichen Änderungen überprüft werden.

Szenario 2: Merge Requests für Updates (Merge-Request-Modus)

Auslöser: Push auf jeden konfigurierten Branch Aktion: Erstellt Merge Request mit Übersetzungsaktualisierungen

lingodotdev:
  image: lingodotdev/ci-action:latest
  variables:
    LINGODOTDEV_API_KEY: $MY_LINGODOTDEV_API_KEY # oder OPENAI_API_KEY/ANTHROPIC_API_KEY
    LINGODOTDEV_PULL_REQUEST: "true"
    LINGODOTDEV_PULL_REQUEST_TITLE: "feat: update translations"
  script:
    - echo "Done"

Ablauf: Inhaltsänderungen werden in den Branch gepusht → Integration erstellt Merge Request mit Übersetzungen

Dies ermöglicht separate Reviews für Übersetzungsaktualisierungen.

Erweiterte Konfiguration

Passen Sie das Integrationsverhalten mit zusätzlichen Variablen an:

Beispiel mit Lingo.dev Engine:

lingodotdev:
  image: lingodotdev/ci-action:latest
  variables:
    LINGODOTDEV_API_KEY: $MY_LINGODOTDEV_API_KEY
    GL_TOKEN: $MY_GL_TOKEN
    LINGODOTDEV_PULL_REQUEST: "true"
    LINGODOTDEV_PULL_REQUEST_TITLE: "feat: update translations"
    LINGODOTDEV_COMMIT_MESSAGE: "feat: update translations via @lingodotdev"
    LINGODOTDEV_WORKING_DIRECTORY: "apps/web"
    LINGODOTDEV_PROCESS_OWN_COMMITS: "true"
  script:
    - echo "Done"
  rules:
    - if: $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH = /^feat/

Beispiel mit Raw-LLM-API:

lingodotdev:
  image: lingodotdev/ci-action:latest
  variables:
    OPENAI_API_KEY: $MY_OPENAI_API_KEY # oder ANTHROPIC_API_KEY
    GL_TOKEN: $MY_GL_TOKEN
    LINGODOTDEV_PULL_REQUEST: "true"
    LINGODOTDEV_PULL_REQUEST_TITLE: "feat: update translations"
    LINGODOTDEV_COMMIT_MESSAGE: "feat: update translations via @lingodotdev"
    LINGODOTDEV_WORKING_DIRECTORY: "apps/web"
    LINGODOTDEV_PROCESS_OWN_COMMITS: "true"
  script:
    - echo "Done"
  rules:
    - if: $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH = /^feat/

Konfigurationsoptionen:

• LINGODOTDEV_API_KEY — Ihr Lingo.dev Engine API-Schlüssel, wenn Sie die Lingo.dev Engine verwenden
• OPENAI_API_KEY — Ihr OpenAI API-Schlüssel, wenn Sie die Raw-LLM-API verwenden
• ANTHROPIC_API_KEY — Ihr Anthropic API-Schlüssel, wenn Sie die Raw-LLM-API verwenden
• LINGODOTDEV_PULL_REQUEST — Merge Request anstelle eines direkten Commits erstellen (Standard: false)
• LINGODOTDEV_PULL_REQUEST_TITLE — Benutzerdefinierter Merge-Request-Titel (Standard: feat: update translations via @lingodotdev)
• LINGODOTDEV_COMMIT_MESSAGE — Benutzerdefinierte Commit-Nachricht (Standard: feat: update translations via @lingodotdev)
• LINGODOTDEV_WORKING_DIRECTORY — Integration in einem Unterverzeichnis ausführen (Standard: .)
• LINGODOTDEV_PROCESS_OWN_COMMITS — Von dieser Integration erstellte Commits verarbeiten (Standard: false)

Fehlerbehebung

Häufige Fehler und ihre Lösungen: