Modul für benutzerdefinierte Dateiformate

Verwende dieses Modul, um Unterstützung für neue benutzerdefinierte Dateiformate hinzuzufügen. Crowdin überträgt das Parsen von Source-Dateien an eine App, die über ein Modul für benutzerdefinierte Dateiformate verfügt. Wenn die Übersetzungen abgeschlossen sind, übergibt Crowdin eine Source-Datei und ein String-Array mit Übersetzungen an die App für benutzerdefinierte Dateiformate, damit diese Übersetzungsdateien generiert.

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

manifest.json

{
  "modules": {
    "custom-file-format": [
      {
        "key": "your-module-key-type-xyz",
        "type": "type-xyz",
        "url": "/process",
        "multilingual": true,
        "customSrxSupported": true,
        "signaturePatterns": {
          "fileName": "^.+\.xyz$",
          "fileContent": "<properties>\s*<property\s+name=.*value=.*/>"
        }
      }
    ]
  }
}

Eigenschaften

key	Typ: string Erforderlich: ja Beschreibung: Kennung des Moduls innerhalb der Crowdin-App.
type	Typ: string Erforderlich: ja Beschreibung: Kennung des benutzerdefinierten Dateiformats. Kann in der API verwendet werden, um die Verarbeitung von Dateien durch die App für benutzerdefinierte Dateiformate zu erzwingen. Wenn der Parameter type in der API verwendet wird, wird signaturePatterns ignoriert. Über diese Eigenschaft definierte Werte können auch von anderen Modulen referenziert werden, beispielsweise über attributes.crowdinType im Modul zur Verarbeitung nach dem Dateiimport.
url	Typ: string Erforderlich: ja Beschreibung: Die relative URL, die beim Dateiimport, bei Aktualisierungen, beim Hochladen von Übersetzungen und beim Export aufgerufen wird.
multilingual	Typ: bool Erforderlich: nein Zulässige Werte: true, false. Standardwert ist false Beschreibung: Dieser Parameter wird verwendet, um den Inhalt mehrerer Sprachen in einer Anfrage zusammenzufassen, wenn Übersetzungen in deinem Crowdin-Projekt hoch- oder heruntergeladen werden.
customSrxSupported	Typ: bool Erforderlich: nein Zulässige Werte: true, false. Standardwert ist false Beschreibung: Gibt an, ob die App benutzerdefinierte Segmentierungsregeln (SRX 2.0) für ihr Dateiformat unterstützt. Wenn aktiviert, können Segmentierungsregeln für die von diesem Modul verarbeiteten Dateien definiert werden und Crowdin übergibt sie im Parameter customSrxContents an die App. Siehe Inhaltssegmentierung.
signaturePatterns	Typ: Objekt Beschreibung: Enthält reguläre Ausdrücke für fileName und/oder fileContent, die zur Erkennung des Dateityps beim Hochladen einer neuen Ausgangsdatei über die Benutzeroberfläche (oder über die API ohne angegebenen type-Parameter) verwendet werden. Wenn die Datei den regulären Ausdrücken entspricht, wird sie als Datei im benutzerdefinierten Format gekennzeichnet. Hinweis Der reguläre Ausdruck für fileContent prüft nur die ersten 64 KB des Dateiinhalts.

Kommunikation zwischen der App für benutzerdefinierte Dateiformate und Crowdin

Beim ersten Dateiimport erkennt Crowdin anhand der Parameter signaturePatterns oder type ein benutzerdefiniertes Dateiformat und sendet eine HTTP-Anfrage an die URL der App ($baseUrl. $url`), damit die Datei weiterverarbeitet werden kann. Die App verarbeitet anschließend die Datei und antwortet Crowdin. Für Anfragen und Antworten von und zu Apps für benutzerdefinierte Dateiformate gilt ein Timeout von zwei Minuten. Die maximale Größe von Request- und Response-Payloads ist auf 5 MB begrenzt.

Anfrage an die App

Beispiel für die Nutzlast der Anfrage:

// max request payload - 5 MB
// wait timeout - 2 minutes
{
  "jobType": "parse-file | build-file",
  "organization": {
    "id": 1,
    "domain": "{domain}",
    "baseUrl": "https://{domain}.crowdin.com",
    "apiBaseUrl": "https://{domain}.api.crowdin.com"
  },
  "project": {
    "id": 1,
    "identifier": "your-project-identifier",
    "name": "Your Project Name"
  },
  "file": {
    "id": 1,
    "name": "file.xml",
    "content": "VGhpcyBpcyBmaWxlIGNvbnRlbnQ=", // base64 encoded source file content
    "contentUrl": "https://crowdin-tmp.downloads.crowdin.com/1/file.xml?aws-signature=..." // source file public URL
  },
  "sourceLanguage": {
    "id": "es",
    "name": "Spanish",
    "editorCode": "es",
    "twoLettersCode": "es",
    "threeLettersCode": "spa",
    "locale": "es-ES",
    "androidCode": "es-rES",
    "osxCode": "es.lproj",
    "osxLocale": "es",
    "pluralCategoryNames": ["one"],
    "pluralRules": "(n != 1)"
  },
  "targetLanguages": [
    {
      // same structure as for sourceLanguage, empty when uploading a new source file, one element for import_translations & export, can be more for multilingual files
    }
  ],
  "strings": [...], // for the build-file jobs, array of segments
  "stringsUrl": "https://tmp.downloads.crowdin.com/strings.ndjson", // for the build-file jobs, file with segments, in new-line delimited json format
  "customSrxContents": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>..." // segmentation rules defined for the file, null if there are none
}

Eigenschaften:

jobType	Typ: string Mögliche Werte: parse-file, build-file Beschreibung: Gibt die Aktion an, die von der App ausgeführt werden soll. Der Auftrag parse-file wird für den erstmaligen Upload von Source-Dateien, die Aktualisierung von Source-Dateien und den Upload von Übersetzungen verwendet. Für parse-file-Aufträge übergibt Crowdin der App eine Source-Datei und erwartet im Antwortkörper ein geparstes Source-String-Array. Der Auftrag build-file wird für den Übersetzungsdownload verwendet. Für build-file-Aufträge übergibt Crowdin der App eine Source-Datei und ein String-Array mit Übersetzungen und erwartet im Antwortkörper eine generierte Übersetzungsdatei.
file.content, file.contentUrl	Typ: string Beschreibung: Parameter zur Übergabe des base64-codierten Inhalts der Source-Datei (file.content) oder einer öffentlichen URL zur Source-Datei (file.contentUrl). Beide Parameter können verwendet werden. Einschränkungen Das maximale Limit für die Nutzlast der Anfrage beträgt 5 MB.
strings, stringsUrl	Typ(strings): array Typ(stringsUrl): string Beschreibung: Parameter für den Übersetzungsdownload (nur für den Auftragstyp build-file). strings – Array mit Übersetzungsstrings. stringsUrl – öffentliche URL zu einem Newline-delimited-JSON mit Übersetzungsstrings. Beide Parameter können verwendet werden. Einschränkungen Das maximale Limit für die Nutzlast der Anfrage beträgt 5 MB.
customSrxContents	Typ: string Beschreibung: Inhalt der für die Source-Datei definierten SRX-2.0-Segmentierungsregeldatei. Wird sowohl für parse-file- als auch build-file-Aufträge übergeben, wenn im Modul die Eigenschaft customSrxSupported aktiviert ist. Wenn keine Segmentierungsregeln für die Datei definiert sind, lautet der Parameter null. Siehe Inhaltssegmentierung.

Erwartete Antwort der App für den Auftragstyp parse-file

Beispiel für die Nutzlast der Antwort:

// max response payload - 5 MB
// wait timeout - 2 minutes
{
  "data": {
    "strings": [...], // segments array
    "stringsUrl": "https://app.example.com/jKe8ujs7a-segments.ndjson", // new-line delimited json file with parsed strings
    "preview": "VGhpbmdzIGFyZSBvbmx5IGltcG9zc2libGUgdW50aWwgdGhleSdyZSBub3Qu", // optional, base64 encoded content of preview html file, not supported if there are plural strings
    "previewUrl": "https://app.example.com/LN3km2K6M-preview.html", // optional, URL of preview html file, not supported if there are plural strings
  },
  "error": {
    "message": "Your error message"
  }
}

Eigenschaften:

data.strings, data.stringsUrl	Typ(data.strings): array Typ(data.stringsUrl): string Beschreibung: Parameter zur Übergabe des Inhalts der geparsten Strings. data.strings – Array mit geparsten Strings. data.stringsUrl – öffentliche URL zu einem Newline-delimited-JSON mit geparsten Strings. Beide Parameter können verwendet werden. Einschränkungen Das maximale Limit für die Nutzlast der Antwort beträgt 5 MB.
data.preview, data.previewUrl	Typ(data.preview): string Typ(data.previewUrl): string Beschreibung: Parameter zur Übergabe der optionalen HTML-Vorschau des geparsten String-Inhalts, die von der App generiert werden kann. Die generierte HTML-Vorschau wird im Editor angezeigt. Siehe das Beispiel für eine HTML-Vorschau der Datei. Achtung Die HTML-Vorschau wird im Crowdin Editor nicht angezeigt, wenn die App Strings mit Pluralformen übergibt.
error.message	Typ: string Beschreibung: Eine Fehlermeldung, die von der App an Crowdin übergeben wird und für einen Benutzer in der Benutzeroberfläche sichtbar ist.

Erwartete Antwort der App für den Auftragstyp build-file

Beispiel für die Nutzlast der Antwort:

// max response payload - 5 MB
// wait timeout - 2 minutes
{
  "data": {
    "content": "TWF5IHRoZSBGb3JjZSBiZSB3aXRoIHlvdS4=", // base64 encoded translation file content
    "contentUrl": "https://app.example.com/p5uLEpq8p-result.xml", // translation file public URL
  },
  "error": {
    "message": "Your error message"
  }
}

Eigenschaften:

data.content, data.contentUrl	Typ(data.content): String Typ(data.contentUrl): String Beschreibung: Parameter, die zum Übergeben des Base64-codierten Inhalts der Übersetzungsdatei (data.content) oder einer öffentlichen URL der Übersetzungsdatei (data.contentUrl) verwendet werden. Beide Parameter können verwendet werden. Einschränkungen Das maximale Limit für die Nutzlast der Antwort beträgt 5 MB.
error.message	Typ: string Beschreibung: Eine Fehlermeldung, die von der App an Crowdin übergeben wird und für einen Benutzer in der Benutzeroberfläche sichtbar ist.

Struktur des String-Arrays

Unten siehst du ein Beispiel für die erwartete Struktur der Strings für den Auftragstyp parse-file, die bei einem Auftragstyp build-file an die App übergeben wird.

Payload Beispiel:

// strings should be in "new-line delimited json" format if they passed by URL
[
  { // non plural string
    "previewId": 1, // only for "parse-file" jobType, required when the HTML preview of the file is generated
    "id": 1, // only for "build-file" jobType
    "identifier": "string-key-1", // required
    "context": "Some context", // optional
    "customData": "max 4 KB of custom data", // optional
    "maxLength": 10, // optional, default null
    "isHidden": false, // optional, default null
    "hasPlurals": false, // optional, default false
    "labels": ["label-one", "label-two"], // optional, default []
    "attributes": { // optional
      "crowdinType": "html" // the string content is re-parsed with the HTML parser
    },
    "text": "String source text", // required
    "translations": { // optional
      "uk": { // targetLanguage.id
        "text": "Переклад стрічки", // required
        "status": "untranslated | translated | approved" // optional, default "translated"
      },
      // can be other languages for multilingual, check "targetLanguages" in the request payload
    }
  },
  { // plural string
    "previewId": 2,
    "id": 2,
    "identifier": "string-key-2",
    "context": "Some optional context",
    "customData": "max 4 KB of custom data",
    "maxLength": 15,
    "isHidden": false,
    "hasPlurals": true,
    "labels": [],
    "text": { // keys from sourceLanguage.pluralCategoryNames
      "one": "One file",
      "other": "%d files",
    },
    "translations": {
      "uk": {
        "text": { // keys from targetLanguage.pluralCategoryNames
          "one": "One file",
          "few": "%d файла",
          "many": "%d файлів",
        },
        "status": {
          "one": "untranslated",
          "few": "translated",
          "many": "approved",
        }
      }
    }
  }
]

Eigenschaften:

previewId	Typ: string oder number Erforderlich: ja (nur für den Auftrag parse-file, wenn die HTML-Vorschau der Datei generiert wird) Beschreibung: Eindeutige Kennung, die den String mit seinem Element in der HTML-Vorschau verknüpft. Ihr Wert muss exakt dem Token {previewId} entsprechen, das im entsprechenden Element in id=“string_preview_id_{previewId}” verwendet wird (siehe HTML-Vorschau der Datei). Wird nur für den Auftragstyp parse-file verwendet.
id	Typ: integer Beschreibung: Numerische ID des Strings in deinem Crowdin-Projekt. Wird nur für den Auftragstyp build-file verwendet.
identifier	Typ: string Beschreibung: Eindeutiger String-Schlüssel innerhalb der Datei.
customData	Typ: string Beschreibung: Beliebige benutzerdefinierte Daten, die mit dem String verknüpft werden müssen. Hinzugefügte benutzerdefinierte Daten werden zusammen mit den entsprechenden Strings beim Übersetzungsexport exportiert.
attributes.crowdinType	Typ: String Zulässige Werte: Entsprechen größtenteils den für die Add File API-Methode akzeptierten type-Werten, mit Ausnahme der folgenden: auto, xml, csv, docx, xlsx, dita, idml, mif, svg. Zusätzlich werden benutzerdefinierte Werte unterstützt, die über die type-Eigenschaft dieses Moduls definiert wurden. Beschreibung: Wird verwendet, um bei erforderlicher Nachbearbeitung den Dateiformattyp eines Strings anzugeben. Wenn ein von der App zurückgegebener String beispielsweise eingebettetes HTML enthält, kannst du durch Setzen von crowdinType auf html den String mithilfe des HTML-Parsers erneut parsen. Crowdin parst und segmentiert solche Inhalte genauso wie eine Datei dieses Formats und führt die Übersetzungen beim Erstellen der Übersetzungsdatei wieder mit dem ursprünglichen String zusammen. Wird nur für den Auftragstyp parse-file verwendet. Siehe Inhaltssegmentierung.

Inhaltssegmentierung

Der Inhalt eines benutzerdefinierten Dateiformats kann auf zwei Arten in kleinere Segmente aufgeteilt werden: Deine App segmentiert den Inhalt selbst mit den von Crowdin übergebenen Regeln oder Crowdin segmentiert den Inhalt mit einem seiner eigenen Parser. Segmentiere ihn in der App, wenn nur deine App den Inhalt parsen kann, und überlasse die Segmentierung einem Crowdin-Parser, wenn ein String Inhalt in einem Format enthält, das Crowdin bereits unterstützt, z. B. HTML oder Markdown.

Inhalte in deiner App segmentieren

Setze die Eigenschaft customSrxSupported in der Modulkonfiguration auf true. Segmentierungsregeln (SRX 2.0) können anschließend für die von diesem Modul verarbeiteten Dateien festgelegt werden, beispielsweise über den Parameter importOptions.srxStorageId der APIs Add File und Update File.

Crowdin übergibt den Inhalt der für eine Datei definierten Regeln im Parameter customSrxContents sowohl bei parse-file- als auch bei build-file-Anfragen. Die App führt die Segmentierung selbst durch:

• Beim Auftrag parse-file teilt die App den Text anhand dieser Regeln auf und gibt jedes Segment als separaten String mit eigener identifier (und eigener previewId, wenn die App die HTML-Vorschau der Datei generiert) zurück.
• Beim Auftrag build-file empfängt die App diese Segmente mit ihren Übersetzungen und setzt sie beim Generieren der Übersetzungsdatei wieder zusammen.

Wenn für eine Datei keine Regeln definiert sind, ist customSrxContents gleich null.

Auch beim Übersetzungsexport wird der Auftrag parse-file verwendet. Gib daher beim Parsen einer Übersetzungsdatei dieselben IDs pro Segment zurück. Andernfalls stimmen die hochgeladenen Übersetzungen nicht mit den vorhandenen Segmenten überein.

Inhalte mit einem Crowdin-Parser segmentieren

Setze das Attribut attributes.crowdinType eines Strings auf das Format seines Inhalts. Crowdin parst einen solchen String anschließend genauso wie eine Datei dieses Formats. Dadurch wird der Inhalt anhand der Projekteinstellungen für dieses Format oder anhand der Standardssegmentierung dieses Formats segmentiert.

Jedes Segment wird zu einem separaten String im Projekt. Beim Auftrag build-file führt Crowdin die Übersetzungen wieder mit dem ursprünglichen String zusammen, sodass die App denselben String erhält, den sie beim Parsen der Datei zurückgegeben hat.

Strings mit Pluralformen werden nicht erneut geparst; in stringbasierten Projekten hat das Attribut keine Auswirkung.

Einschränkungen

Jedes Segment zählt als separater String, sodass segmentierte Dateien die Payload-Limits von 5 MB für Anfragen und Antworten schneller erreichen.

HTML-Vorschau der Datei

Die HTML-Vorschau rendert im Editor eine WYSIWYG-Ansicht der Datei. Umschließe jeden übersetzbaren String mit einem Element, das beide folgenden Attribute enthält:

• id="string_preview_id_{previewId}", wobei {previewId} mit der previewId des entsprechenden Strings aus der parse-file-Antwort übereinstimmt. Verwende doppelte Anführungszeichen und stelle sicher, dass der Wert exakt übereinstimmt.
• class="crowdin_phrase", damit der Editor den String in der Vorschau hervorheben und direkt darin bearbeiten kann. Ohne diese Klasse wird der String nur hervorgehoben, wenn er aus der String-Liste ausgewählt wird, und die direkte Bearbeitung in der Vorschau funktioniert nicht.

Wenn die App einen String in mehrere Segmente aufteilt, gib jedem Segment eine eigene previewId und ein eigenes Element in der Vorschau. Wenn mehrere Segmente dieselbe previewId verwenden, wird nur das letzte mit dem Element verknüpft.

Die HTML-Vorschau wird nur beim Import der Source-Datei generiert. Sie wird beim Hochladen von Übersetzungen (einschließlich mehrsprachiger Uploads) nicht erzeugt und nicht angezeigt, wenn die App Strings mit Pluralformen übergibt.

Beispiel für die HTML-Vorschau der Datei:

<html lang="en">
  <head>
    <title>Optional Title</title>
    <style>
      table, th, td {
        border: 1px solid #aaa;
      }
    </style>
  </head>
  <body>
    <h1 style="text-align: center">HTML preview of the file</h1>
    <table style="width: 100%">
      <tr>
        <th>Key:</th>
        <th>Text:</th>
      </tr>
      <tr>
        <td>Key 1</td>
        <td><span id="string_preview_id_1" class="crowdin_phrase">Source Text 1</span></td> <!-- 1 is previewId in strings json -->
      </tr>
      <tr>
        <td>Key 2</td>
        <td><span id="string_preview_id_2" class="crowdin_phrase">Source Text 2</span></td> <!-- 2 is previewId in strings json -->
      </tr>
    </table>
  </body>
</html>