File Pre-Export Processing Module

The pre-export module allows you to modify the strings before the file export. This module works with both the source strings and their respective translations. The pre-export module is especially useful if you’d like to preserve the original file structure and export it as it is but want to make some changes to translated strings.

With the help of the pre-export module, you will get a payload with the file content and strings for export. Using the pre-export module, you can modify translated strings and return them for export. This allows you to customize the strings without directly modifying the file content.

Note: If your file processing app has changed the string quantity using the post-import module, make sure that the pre-export module returns the original string quantity along with their string uniqId.

Structure

{
  "file-pre-export": [
    {
      "key": "your-pre-export-module-key",
      "url": "/export-strings",
      "signaturePatterns": {
        "fileName": "^.+\\.xml$",
        "fileContent": "<properties>\\s*<property\\s+name=.*value=.*/>"
      }
    }
  ]
}

Properties

key

Type: string

Required: yes

Description: Module identifier within the Crowdin app.

url

Type: string

Required: yes

Description: The relative URL triggered on file export.

signaturePatterns

Type: object

Description: Contains fileName and/or fileContent regular expressions used to detect file type when exporting a translation file.

Note: fileContent regular expression checks only the first 64 KB of the file content.

Communication between File Processing App and Crowdin

When exporting a file, the system detects an appropriate pre-export module using the signaturePatterns parameter and makes an HTTP request to the app’s URL ($baseUrl . $url) for further processing containing the source strings and their respective translations.

The file processing app will modify the string translations according to your needs. Make sure that the pre-export module returns the original string quantity along with their string uniqId to ensure a successful translation export. Once the modified strings are returned from the pre-export module, they are used to build a translation file.

Request to the File Processing App

Request payload example:

// max request payload - 5 MB
// wait timeout - 2 minutes
{
    "jobType": "file-pre-export",
    "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, one element for export, can be more for miltilingual files
    }],
    "strings": [...],
    "stringsUrl": "https://tmp.downloads.crowdin.com/strings.ndjson",
}

Properties:

jobType

Type: string

Value: file-pre-export

Description: Specifies the action of the file pre-export module.

file.content, file.contentUrl

Type: string

Description: Parameters used to pass the base64 encoded source file content (file.content) or a source file public URL (file.contentUrl).
Either of these two parameters can be used (Note: Maximum request payload limit is 5 MB).

strings, stringsUrl

Type(strings): array

Type(stringsUrl): string

Description: Parameters used for the source strings and their respective translations before the file export. strings - strings array. stringsUrl - public URL to a new-line delimited json with strings.
Either of these two parameters can be used (Note: Maximum request payload limit is 5 MB).

Expected Response from the App for the file-pre-export Job Type

Response payload example:

// max response payload - 5 MB
// wait timeout - 2 minutes
{
    "data": {
        "strings": [...], // modified strings array
        "stringsUrl": "https://app.example.com/jKe8ujs7a-segments.ndjson", // new-line delimited json file with modified strings
    },
    "error": {
        "message": "Your error message"
    }
}

Properties:

data.strings, data.stringsUrl

Type(data.strings): array

Type(data.stringsUrl): string

Description: Parameters used to pass the modified strings content.
data.strings - modified strings array.
data.stringsUrl - public URL to a new-line delimited json with modified strings.
Either of these two parameters can be used (Note: Maximum response payload limit is 5 MB).

error.message

Type: string

Description: An error message that can be passed from the app to Crowdin and will be visible to a user in the UI.

Strings Array Structure

Below you can see an example of the strings that app will receive before the export. The same structure is used for the modified strings in the app response.

Payload example:

// strings should be in "new-line delimited json" format if they passed by URL
[
    { // non plural string
        "uniqId": "9cdfb439c7876e703e307864c9167a15::1", // required, unique ID 
        "identifier": "string-key-1", // required
        "context": "Some context", // optional
        "maxLength": 10, // optional, default null
        "isHidden": false, // optional, default null
        "hasPlurals": false, // optional, default false
        "labels": ["label-one", "label-two"], // optional, default []
        "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
        "uniqId": "9cdfb439c7876e703e307864c9167a15::2", // required, unique ID
        "identifier": "string-key-2",
        "context": "Some optional context",
        "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"
                }
            }
        }
    }
]

Properties:

uniqId

Type: string

Description: Unique identifier within the file.

identifier

Type: string

Description: Visible string key.

Var denne artikel nyttig?