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

Die GitHub-App installieren#

1. Öffnen Sie in Lingo.dev Ihre Organisation.
2. Gehe zu Studio > All integrations.
3. Klicke auf der GitHub-Karte auf Install on GitHub.
4. Wählen Sie auf GitHub das Konto oder die Organisation aus, in dem bzw. der Sie die App installieren möchten.
5. Wählen Sie entweder Alle Repositories oder Nur ausgewählte Repositories.
6. Klicken Sie auf Installieren.

GitHub leitet Sie zurück zu Lingo.dev – zum Bildschirm Connect GitHub:

1. Wählen Sie die Lingo.dev-Organisation aus, über die dieses GitHub-Konto lokalisiert. Die zuletzt von Ihnen geöffnete Organisation ist bereits vorausgewählt.
2. Klicken Sie auf Connect.
3. Sobald GitHub connected angezeigt wird, klicken Sie auf View integration, um die Verbindung zu öffnen.

Die Verbindung erscheint in der Studio-Seitenleiste unter Connected. Auf der Registerkarte Settings sehen Sie Account, Account type, Installation, Repositories und ob die Connection funktioniert. Die Registerkarte Workflow runs listet jeden Lauf der App auf – zusammen mit dem Repository und der Information, ob er durch einen Push oder einen Pull Request gestartet wurde.

Wenn Sie später Repositorys hinzufügen oder entfernen möchten, öffnen Sie die Registerkarte Settings der Verbindung und verwenden Sie Manage on GitHub: Der Repository-Zugriff wird immer direkt in GitHub auf der Installation selbst festgelegt.

Wenn Sie die Installation angefordert haben, statt sie zu installieren, zeigt Lingo.dev Installation requested an: Eine GitHub-Organisationsadministratorin oder ein GitHub-Organisationsadministrator muss die Anfrage genehmigen. Sobald das passiert, bringt GitHub Sie zurück zum Bildschirm Connect GitHub, damit Sie den Vorgang abschließen können. Die Administratorin oder der Administrator kann die Anfrage in GitHub im Bereich Settings > GitHub Apps der Organisation ansehen. GitHub zeigt Organisationsinhabern außerdem ausstehende App-Anfragen 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.

String Catalogs sind die Ausnahme. Da eine einzige .xcstrings-Datei alle Sprachen enthält, entspricht der Zielpfad dem Quellpfad – die App schreibt jede Sprache in genau diese Datei und fügt weder ein Sprachverzeichnis noch einen Dateinamen hinzu.

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
• Xcode String Catalog (.xcstrings)

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" }
  ]
}

Xcode String Catalogs#

Ein Xcode String Catalog speichert alle Sprachen in einer einzigen .xcstrings-Datei. Deshalb übersetzt die App direkt in diese Datei, statt für jede Sprache eine eigene Datei zu erstellen. Der Zielpfad entspricht dem Quellpfad: Jede Zielsprache wird in dieselbe Datei geschrieben – zusammen mit der Ausgangssprache und allen bereits übersetzten Sprachen. Richten Sie das Quellmuster direkt auf den Katalog und setzen Sie sourceLocale auf seine Entwicklungssprache:

{
  "sourceLocale": "en",
  "targetLocales": ["es-MX", "fr-CA", "pt-BR"],
  "files": [{ "pattern": "**/*.xcstrings" }]
}

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#