GitHub App

Die Lingo.dev GitHub App richtet mit .lingo/config.json eine kontinuierliche Lokalisierung für ein Repository ein.

Voraussetzungen#

Bevor Sie die App installieren, stellen Sie sicher, dass Sie Folgendes haben:

• Eine Lingo.dev-Organisation mit aktivierter GitHub-Integration
• Eine Lokalisierungs-Engine in dieser Organisation
• Admin-Zugriff auf die GitHub-Organisation oder das Repository, das Sie verbinden möchten

GitHub App verbinden#

1. Öffnen Sie in Lingo.dev Ihre Organisation.
2. Gehen Sie zu Einstellungen.
3. Suchen Sie im Bereich „Integrationen“ nach GitHub (App).
4. Klicken Sie in der Zeile GitHub (App) auf Verbinden.
5. Wählen Sie auf GitHub das Konto oder die Organisation aus, in dem bzw. der Sie die App installieren möchten.
6. Wählen Sie entweder Alle Repositories oder Nur ausgewählte Repositories.
7. Klicken Sie auf Installieren.

Nach der Installation zeigt Lingo.dev das verbundene GitHub-Konto und die Repositories unter Einstellungen > GitHub (App) an. Über Repositories auf GitHub verwalten auf derselben Einstellungskarte können Sie später Repositories hinzufügen oder entfernen.

Wenn Ihre Installationsanfrage noch auf Genehmigung wartet, kann ein GitHub-Admin sie in GitHub im Bereich Einstellungen > GitHub Apps der Organisation prüfen. GitHub zeigt ausstehende App-Anfragen außerdem den Eigentümern der Organisation in den Organisationseinstellungen an.

Repository-Konfiguration hinzufügen#

Erstellen Sie .lingo/config.json in dem Repository, in dem Sie die App installiert haben:

{
  "engineId": "eng_abc123",
  "sourceLocale": "en",
  "targetLocales": ["es", "fr", "de"],
  "files": [
    { "pattern": "docs/en/**/*.md" },
    { "pattern": "docs/en/**/*.mdx" },
    { "pattern": "locales/en.json" }
  ],
  "github": {
    "workflows": {
      "onPushToDefaultBranch": { "enabled": true },
      "onPullRequest": { "enabled": true }
    },
    "safety": {
      "requireApproval": false
    }
  }
}

Dateimuster#

files-Muster verweisen auf Quelldateien in der Quelle (Standard-Sprache). Die App gleicht geänderte Dateien mit diesen Mustern ab und verarbeitet nur unterstützte Quelldateien, die dazu passen.

Muster sind repository-relativ, unterscheiden zwischen Groß- und Kleinschreibung und können Folgendes verwenden:

• * für Treffer innerhalb eines Pfadsegments
• **/ für Treffer über beliebige Verzeichnistiefen hinweg

Muster dürfen nicht mit / beginnen und .. nicht enthalten.

{
  "files": [
    { "pattern": "docs/en/**/*.md" },
    { "pattern": "src/content/en/**/*.mdx" },
    { "pattern": "messages/en.jsonc" }
  ]
}

Dateioptionen#

Jeder Eintrag in files kann zusätzlich zu seinem pattern weitere Optionen enthalten. Alle sind optional und gelten jeweils nur für bestimmte Formate.

translateComponentProps-Einträge sind entweder ein Prop-Name, der für dieses Prop auf jeder Komponente oder jedem Tag gilt, oder ein Objekt, das die Props auf benannte Komponenten oder Tags einschränkt:

{
  "files": [
    {
      "pattern": "src/content/en/**/*.mdx",
      "translateFrontmatterFields": ["title", "description"],
      "translateComponentProps": [
        "alt",
        { "component": ["Callout", "Hero"], "props": ["title", "subtitle"] }
      ]
    },
    {
      "pattern": "locales/en.json",
      "lockedKeys": ["app.version"],
      "injectLocale": { "enabled": true, "key": "language" }
    }
  ]
}

Wo lokalisierte Dateien gespeichert werden#

Die App leitet jeden Zielpfad aus dem Quellpfad und den Sprachcodes in Ihrer Konfiguration ab:

Verwenden Sie den vollständigen Verzeichnisnamen oder Dateinamen als Sprachcode. Wenn sich Quelldateien zum Beispiel in docs/en-US/ befinden, setzen Sie "sourceLocale": "en-US" und nicht "en". Wenn sich Quelltexte in messages/en.json befinden, setzen Sie "sourceLocale": "en".

Wenn der Quellpfad ein Sprachverzeichnis enthält, ersetzt die App dieses Verzeichnis. Wenn der Quellpfad eine Datei mit Sprachcode im Namen ist, ersetzt die App den Dateinamen. Wenn keines von beidem zutrifft, legt die App die übersetzte Datei in einem neuen Verzeichnis für die Zielsprache neben der Quelldatei ab.

Workflows#

Push auf den Standard-Branch#

Wenn auf dem Standard-Branch eine passende Quelldatei hinzugefügt oder geändert wird, übersetzt die App sie und committed die lokalisierten Dateien nach:

lingo/translations/<default-branch>

Anschließend öffnet oder aktualisiert sie einen Pull Request von diesem Übersetzungs-Branch zurück in den Standard-Branch. Wenn der Übersetzungs-Branch bereits existiert, werden neue Commits daran angehängt.

Wenn im selben Push eine Zieldatei hinzugefügt oder geändert wird, behandelt die App diese Datei als bereits verarbeitet und übernimmt sie in den Übersetzungs-PR, statt sie zu überschreiben.

Pull Requests#

Wenn github.workflows.onPullRequest.enabled auf true gesetzt ist, prüft die App Änderungen in Pull Requests auf passende Quelldateien. Übersetzte Dateien committed sie direkt in den PR-Branch.

Die App schreibt nicht in PR-Branches aus Forks und schreibt aus einem PR-Kommentar nicht in den Standard-Branch. Pull Requests müssen geöffnet sein, damit die App Übersetzungen committen kann.

Bei PRs aktualisiert Lingo.dev einen PR-Kommentar mit den übersetzten Dateien und allen Fehlern.

Inkrementelle Updates und Wiederherstellung#

Bei vorhandenen Zieldateien übersetzt die App nur die erkennbaren Änderungen in der Quelle, statt die gesamte Datei neu zu erzeugen. Für neue Zieldateien erstellt sie für jede konfigurierte Zielsprache eine lokalisierte Datei.

Wenn bei einer früheren PR-Lokalisierung eine Änderung in der Quelle übersehen wurde oder ein Fehler auftrat, bevor die Zieldatei aktualisiert wurde, kann die nächste PR-Synchronisierung das korrigieren, indem sie die PR-Quelle mit der Quelle des Basis-Branches vergleicht und die fehlende Änderung übersetzt.

Wenn eine Quelldatei im gerade verarbeiteten Commit nicht mehr existiert, überspringt die App sie.

Genehmigungsmodus#

Setzen Sie github.safety.requireApproval auf true, wenn Sie einen menschlichen Freigabeschritt wünschen, bevor automatische Übersetzungen ausgeführt werden.

Bei Pushes auf den Standard-Branch zeigt der Lingo.dev-Check-Run die Aktionen Approve und Deny an. Bei Pull Requests veröffentlicht die App einen Kommentar mit einem Übersetzungsvorschlag. Antworten Sie mit:

/lingo approve

Bereichsbezogene /lingo translate-Befehle erfordern diese Freigabe nicht.

Manueller PR-Befehl#

Verwenden Sie /lingo in einem Pull-Request-Kommentar, um Übersetzungen für bestimmte Dateien nachzutragen oder zu erzwingen.

/lingo translate docs/en/**/*.md

/lingo translate docs/en/**/*.mdx --locales fr,es

/lingo translate docs/en/**/*.md --force

Befehlsreferenz:

Der Befehl muss in einer eigenen Zeile stehen. Globs werden mit Dateien abgeglichen, die auch zu Ihren konfigurierten files-Quelldateimustern passen. Wie Konfigurationsmuster dürfen Befehls-Globs nicht mit / beginnen und .. nicht enthalten.

Standardmäßig läuft /lingo translate im Nachtragsmodus: Es erstellt nur Zieldateien, die im PR-Branch fehlen. Fügen Sie --force hinzu, wenn Sie vorhandene Zieldateien neu erzeugen möchten.

Unterstützte Formate#

Die GitHub App erkennt diese Formate anhand der Dateiendung:

• JSON (.json)
• JSONC (.jsonc)
• Markdown (.md)
• MDX (.mdx)
• Markdoc

In YAML geschriebene OpenAPI-Dokumente werden ebenfalls unterstützt, aber nicht automatisch erkannt. Setzen Sie "format": "yaml-openapi" für das Dateimuster:

{
  "files": [
    { "pattern": "openapi/en.yaml", "format": "yaml-openapi" }
  ]
}

Große Updates#

Die App kann die Übersetzungsausgabe auf mehrere Commits aufteilen. Das passiert, wenn ein Lauf mehr als 100 Dateien in einem Commit schreiben würde oder mehr als 5 MB übersetzten Dateiinhalt in einem Commit.

In diesem Fall enthalten die Commit-Nachrichten die Batch-Nummer, zum Beispiel:

feat: Lingo.dev translations (1/3)
feat: Lingo.dev translations (2/3)
feat: Lingo.dev translations (3/3)

Was passiert, wenn es keine Treffer gibt#

Wenn .lingo/config.json fehlt, überspringt die App das Repository stillschweigend. Sobald die Konfiguration vorhanden ist, führt eine ungültige Konfiguration zu einem fehlgeschlagenen Check-Run und bei PRs zu einem Kommentar mit dem Validierungsfehler.

Wenn keine geänderten Dateien zu Ihren Quelldateimustern passen, wird die App abgeschlossen, ohne Übersetzungen zu schreiben. Bei /lingo translate antwortet der Bot mit einer kurzen Erklärung, zum Beispiel: keine passenden Dateien, keine passenden Sprachen oder alle Zieldateien sind bereits vorhanden.

Nächste Schritte#