Benutzerdefiniertes MT-Modul

Mit diesem Modul kannst du maschinelle Übersetzungs-Engines verbinden, die von Crowdin noch nicht unterstützt werden. Nachdem du eine solche App erstellt hast, kannst du deine Inhalte mit der verbundenen MT-Engine automatisch übersetzen oder von ihr erstellte Übersetzungsvorschläge im Editor für Übersetzer anzeigen lassen.

Zugriff

Du kannst Zugriff auf dieses Modul für eine der folgenden Benutzerkategorien gewähren:

Für Crowdin:

Nur ich (also der Projektinhaber)
Alle Projektmitglieder
Ausgewählte Benutzer

Für Crowdin Enterprise:

Nur Organisationsadministratoren
Alle Benutzer in den Projekten der Organisation
Ausgewählte Benutzer

Struktur

{
  "modules": {
    "custom-mt": [
      {
        "key": "custom-mt",
        "name": "Benutzerdefinierte MT",
        "logo": "/logo.png",
        "url": "/translate",
        "withContext": true,
        "batchSize": 10,
        "splitStringsIntoChunks": true
      }
    ]
  }
}

Eigenschaften

`key`	Typ: `string` Erforderlich: ja Beschreibung: Kennung des Moduls innerhalb der Crowdin-App.
`name`	Typ: `string` Erforderlich: ja Beschreibung: Der für Menschen lesbare Name des Moduls.
`logo`	Typ: `string` Erforderlich: ja Beschreibung: Die relative URL zum Logo der benutzerdefinierten MT-Engine, das in der Crowdin-Oberfläche angezeigt wird. Die empfohlene Auflösung beträgt 48×48 Pixel.
`url`	Typ: `string` Erforderlich: ja Beschreibung: Die relative URL zur Inhaltsseite des Moduls, die in Crowdin integriert wird.
`withContext`	Typ: `boolean` Erforderlich: nein Beschreibung: Zusätzliche Metadaten, die zusammen mit den Strings gesendet werden.
`batchSize`	Typ: `integer` Erforderlich: nein Beschreibung: Die maximale Anzahl von Strings, die in einer Anfrage an die Custom-MT-App gesendet werden können.
`splitStringsIntoChunks`	Typ: `boolean` Erforderlich: nein Standard: `true` Beschreibung: Steuert die Batch-Verarbeitung. Wenn `false` festgelegt ist, werden alle Strings einer Datei in einer einzigen Anfrage an die MT-Engine gesendet. Wenn `true` (Standard) festgelegt ist, teilt Crowdin die Strings in Chunks auf.
`environments`	Typ: `string` Zulässige Werte: `crowdin`, `crowdin-enterprise` Beschreibung: Menge der Umgebungen, in denen ein Modul installiert werden kann. Dieser Parameter wird für produktübergreifende Anwendungen benötigt.

Kommunikation zwischen der benutzerdefinierten MT-App und Crowdin

Das System sendet Texte zur Übersetzung über url. Anschließend verarbeitet die App die Texte und antwortet mit einer von zwei möglichen Arten von Antworten: ohne Fehler oder mit Fehlern.

HTTP-Anfrage:

https://{AppBaseUrl}/translate/?source=en&target=uk&project_id=727186&jwtToken={yourTokenValue}

Abfrageparameter

`source`	Typ: `string` Beschreibung: Quellsprache.
`target`	Typ: `string` Beschreibung: Zielsprache.
`project_id`	Typ: `integer` Beschreibung: Numerische ID eines Crowdin-Projekts.
`jwtToken`	Typ: `string` Beschreibung: JWT-Token, das zur Autorisierung verwendet wird.
`strings`	Typ: `string` Beschreibung: Source-Strings, die übersetzt werden müssen.

Anfrage von Crowdin an die App für `applicationUrl` (einfach)

Beispiel für die Nutzlast der Anfrage:

{
  "strings": [
    "Save as...",
    "New file",
    "You received one message.",
    "You received {number} messages."
  ]
}

Anfrage von Crowdin an die App für `applicationUrl` (erweitert)

Um die erweiterte Anfrage zu verwenden, füge deinem Custom-MT-Modul den Parameter withContext hinzu.

Beispiel für die Nutzlast der Anfrage:

{
  "strings": [
    {
      "id": 1,
      "projectId": 727186,
      "fileId": 47047,
      "text": "Speichern unter …",
      "identifier": "save_as",
      "context": "translation Context",
      "maxLength": 15,
      "isHidden": false,
      "isPlural": false,
      "pluralForm": null
    },
36 ausgeblendete Zeilen
    {
      "id": 2,
      "projectId": 727186,
      "fileId": 47047,
      "text": "Neue Datei",
      "identifier": "new_file",
      "context": "translation Context",
      "maxLength": null,
      "isHidden": false,
      "isPlural": false,
      "pluralForm": null
    },
    {
      "id": 3,
      "projectId": 727186,
      "fileId": 47047,
      "text": "Du hast eine neue Nachricht erhalten.",
      "identifier": "new_message",
      "context": "translation Context",
      "maxLength": null,
      "isHidden": false,
      "isPlural": true,
      "pluralForm": "one"
    },
    {
      "id": 3,
      "projectId": 727186,
      "fileId": 47047,
      "text": "Du hast {number} neue Nachrichten erhalten.",
      "identifier": "new_message",
      "context": "translation Context",
      "maxLength": null,
      "isHidden": false,
      "isPlural": true,
      "pluralForm": "other"
    }
  ]
}

Erwartete Antwort der App (ohne Fehler)

Beispiel für die Nutzlast der Antwort:

{
  "data": {
    "translations": [
      "Speichern unter …",
      "Neue Datei",
      "Du hast eine neue Nachricht erhalten.",
      "Du hast {number} neue Nachrichten erhalten."
    ]
  }
}

Das translations-Array muss innerhalb des obersten data-Objekts verschachtelt sein. Eine Antwort, die das Array auf oberster Ebene zurückgibt (z. B. {"translations": [...]}), wird als Antwort ohne Übersetzungen behandelt und abgelehnt.

Gib genau eine Übersetzung pro Source-String zurück, und zwar in derselben Reihenfolge, in der die Strings empfangen wurden. Crowdin ordnet Übersetzungen anhand ihrer Position im Array den Source-Strings zu, nicht anhand der ID. Wenn die Anzahl der zurückgegebenen Übersetzungen nicht mit der Anzahl der gesendeten Strings übereinstimmt, wird dieser Batch übersprungen.

Bei großen Payloads kannst du statt des Inline-translations-Arrays translationsUrl zurückgeben.

{
  "data": {
    "translationsUrl": "https://app.example.com/jKe8ujs7a-translations.ndjson"
  }
}

translationsUrl ist eine öffentliche URL zu einer Newline-delimited-JSON-Datei mit den übersetzten Strings. Verwende entweder translations oder translationsUrl.

Erwartete Antwort der App (mit Fehlern)

Beispiel für die Nutzlast der Antwort:

{
  "error": {
    "message": "Error message from the App or MT engine"
  }
}

Die Struktur der Antworten der App muss den dargestellten Beispielen entsprechen. Andernfalls betrachtet Crowdin sie als ungültig.

Batch-Verarbeitung und Dateikontext

Standardmäßig teilt Crowdin Source-Strings in kleinere Chunks auf (splitStringsIntoChunks: true), um die Verarbeitungszeit zu optimieren und die Größe von Anfragen zu verwalten.

Einige moderne MT-Engines und AI-Anbieter (z. B. XL8 oder LLMs) benötigen jedoch den vollständigen Kontext einer Datei, um hochwertige Übersetzungen zu erzeugen. Dies ist besonders bei Formaten wie Untertiteln (SRT) oder literarischen Inhalten wichtig, bei denen die Übersetzung eines Satzes stark vom vorherigen abhängt.

Wenn du eine Engine verbindest, die datei- oder dokumentbasierte Übersetzungen unterstützt:

Setze splitStringsIntoChunks in deinem Manifest auf false.
Crowdin sendet alle Strings, die zu einer Datei gehören, in einer einzigen Anfrage.

Umgang mit nicht übersetzbaren Elementen durch deine MT-Engine

Bei Strings, die nicht übersetzbare Elemente enthalten (z. B. Tags, Platzhalter usw.), ersetzt Crowdin diese Elemente durch spezielle notranslate-Tags. Dadurch bleibt der ursprüngliche Zustand dieser Elemente erhalten, nachdem der String von der MT-Engine übersetzt wurde. Crowdin verwendet diesen Ansatz, um potenzielle Probleme zu vermeiden, die exportierte Übersetzungsdateien beschädigen könnten.

Unten siehst du Beispiele für einen String vor und nach der Änderung.

Hier siehst du ein Beispiel dafür, wie ein String mit nicht übersetzbaren Elementen (Tags, Platzhaltern usw.) in Crowdin aussieht:

<strong>Aufgabe:</strong>

So verändert Crowdin den oben genannten String, bevor er an die MT-Engine gesendet wird:

<span class="notranslate">0</span>Aufgabe:<span class="notranslate">1</span>

Nicht übersetzbare Elemente für deine MT-Engine anpassen

Wenn deine MT-Engine bereits über eine ähnliche Funktion verfügt, diese aber anders als Crowdin implementiert, empfehlen wir, den Umgang mit nicht übersetzbaren Elementen in deiner Custom-MT-App an die Implementierung deiner MT-Engine anzupassen. Ersetze insbesondere Crowdins Standardwerte wie

<span class="notranslate">%index%</span>

durch die spezifischen Nicht-Übersetzen-Elemente deiner MT-Engine.

Hier findest du ein Implementierungsbeispiel für Nicht-Übersetzen-Elemente in Amazon Translate: Using do-not-translate in Amazon Translate.

Umgang mit Übersetzungen mit veränderten nicht übersetzbaren Elementen

Wenn die MT-Engine eine Übersetzung an Crowdin sendet, die nicht alle Tags in ihrem ursprünglichen Zustand enthält oder bei der sie verändert wurden (z. B. übersetzt), ignoriert Crowdin solche Übersetzungen und speichert sie nicht im String.

Fehlerbehebung

Wenn die Custom-MT-App eine Antwort zurückgibt, die Übersetzungen aber nicht gespeichert werden, entspricht der Antwort-Body höchstwahrscheinlich nicht dem erwarteten Schema. Wenn eine Antwort abgelehnt wird, enthält Crowdin den empfangenen Statuscode und den Body in der Fehlermeldung, sodass du ihn mit dem oben beschriebenen Schema vergleichen kannst.

Fehlermeldung	Wahrscheinliche Ursache	Lösung
Custom-MT-Engine hat keine Übersetzungen zurückgegeben	Das `translations`-Array fehlt, ist leer oder befindet sich außerhalb des `data`-Objekts (z. B. auf oberster Ebene).	Verschachtle das `translations`-Array unter dem `data`-Objekt und stelle sicher, dass es nicht leer ist.
Custom-MT-Engine hat eine ungültige Übersetzung zurückgegeben	Eines der Elemente im `translations`-Array ist kein String.	Gib jede Übersetzung als einfachen String zurück.
Custom-MT-Engine hat eine unerwartete Antwort zurückgegeben	Der Antwort-Body ist kein gültiges JSON.	Gib einen korrekt formatierten JSON-Body zurück, der dem erwarteten Schema entspricht.
Custom-MT-Engine hat einen HTTP-Fehler zurückgegeben	Der Endpunkt hat mit einem HTTP-Statuscode außerhalb des Bereichs 2xx geantwortet.	Gib bei erfolgreichen Übersetzungen HTTP 200 zurück und verwende zum Melden von Fehlern das Fehlerantwortformat.

Einige Antworten werden ohne Fehlermeldung abgelehnt. Wenn die Anzahl der zurückgegebenen Übersetzungen nicht mit der Anzahl der gesendeten Source-Strings übereinstimmt, überspringt Crowdin diesen Batch und lässt die betreffenden Strings unübersetzt. Stelle sicher, dass deine App genau eine Übersetzung pro Source-String und in derselben Reihenfolge zurückgibt.

War diese Seite hilfreich?