File Post-Import Processing Module

The post-import module allows you to modify the strings parsed from your files after the file import. This module works with both the source strings and their respective translations. The pre-import module is especially useful if you’d like to preserve the original file structure and parse it as it is but want to make some changes to source strings, context, string translations or add labels, and maximum length limits for translations, etc.

With the help of the post-import module, you will get a payload with the file content and strings parsed from it. Using the post-import module, you can modify the parsed strings in a number of ways (e.g., split, merge, or add new strings) and return the modified strings. This allows you to customize the strings without directly modifying the file content.

Access

You can grant access to this module to one of the following user categories:

For Crowdin:

• Only me (i.e., project owner)
• All project members
• Selected users

For Crowdin Enterprise:

• Only organization admins
• All users in the organization projects
• Selected users

Structure

manifest.json

{
  "modules": {
    "file-post-import": [
      {
        "key": "your-post-import-module-key",
        "url": "/import-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 import, update, and translation upload.
signaturePatterns	Type: object Description: Contains fileName and/or fileContent regular expressions used to detect file type when uploading a new source file via UI (or via API without specified type parameter). Note fileContent regular expression checks only the first 64 KB of the file content.

Communication between File Processing App and Crowdin

When importing a file, the system detects an appropriate post-import module using the signaturePatterns parameter and makes an HTTP request to the app’s URL ($baseUrl . $url) for further processing containing the extracted strings.

The file processing app will modify the received strings according to your needs. The post-import module allows you to split, merge, add new strings, or edit the attributes of the existing ones. Once the modified strings are returned from the post-import module, they are added to the Crowdin project and become available for translation.

Request to the File Processing App

Request payload example:

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

Properties:

jobType	Type: string Value: file-post-import Description: Specifies the action of the file post-import 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. Limitations Maximum request payload limit is 5 MB.
strings, stringsUrl	Type(strings): array Type(stringsUrl): string Description: Parameters used for extracted strings after the file import. strings - strings array. stringsUrl - public URL to a new-line delimited json with strings. Either of these two parameters can be used Limitations Maximum request payload limit is 5 MB.

Expected Response from the App

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
    "preview": "VGhpbmdzIGFyZSBvbmx5IGltcG9zc2libGUgdW50aWwgdGhleSdyZSBub3Qu", // optional, base64 encoded content of preview html file
    "previewUrl": "https://app.example.com/LN3km2K6M-preview.html", // optional, URL of preview html file
  },
  "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. Limitations Maximum response payload limit is 5 MB.
data.preview, data.previewUrl	Type(data.preview): string Type(data.previewUrl): string Description: Parameters used to pass the optional HTML preview of the parsed strings content, which can be generated by the app. The generated HTML preview will be displayed in the Editor. Elements of the preview are linked to strings by their position in the response. See HTML Preview of the File. Caution The previewId string property and the id=“string_preview_id_{previewId}” elements used in the Custom File Format module aren’t supported in this module.
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 after the import. 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 []
    "attributes": {
      "crowdinType": "json"
    },
    "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.
attributes.crowdinType	Type: string Allowed values: Mostly match the type values accepted by the Add File API method, excluding the following: auto, xml, csv, docx, xlsx, dita, idml, mif, svg. Additionally, custom values defined via the type property in the Custom File Format module are also supported. Description: Used to specify the file format type for a string when post-processing is needed. For example, if a JSON file contains strings with embedded HTML, setting crowdinType to html allows to re-parse the string using the HTML parser. This helps ensure correct rendering and prevents unwanted tags from being displayed. Crowdin parses and segments such content the same way as a file of that format, and merges the translations back into the original string when generating the translation file. The value must match one of the supported Crowdin file types or a custom file format identifier.

HTML Preview of the File

The HTML preview renders a WYSIWYG view of the file in the Editor. Wrap each translatable string in an element that carries both of the following:

• id="crowdin_phrase_index_{N}", where {N} is the zero-based position of the string in the app’s response (in data.strings or in the file at data.stringsUrl). Use double quotes and make the value match exactly.
• class="crowdin_phrase", so the string can be selected and edited inline by clicking it in the preview.

Count positions in the strings the app returns, after it splits, merges, or adds strings. If the app changes the number or order of strings, return a preview so that it matches the returned strings.

If the returned strings include attributes.crowdinType, return the preview in both responses. Crowdin sends a second request only when the first response has a preview, and in that request the nested content is already parsed into separate strings. Crowdin uses only the preview from the second response, and {N} counts the strings in that response.

Crowdin uses the HTML preview only when a source file is imported or updated, and ignores it when translations are uploaded.

The preview is also displayed for files that contain plural strings. It shows one form of each plural string at a time. To display another form, select it in the translation field. We recommend translating plural strings there rather than inline in the preview.

HTML Preview of the file example:

<!DOCTYPE html>
<html>
  <body>
    <h1>HTML preview of the file</h1>
    <p><span id="crowdin_phrase_index_0" class="crowdin_phrase">Source Text 1</span></p> <!-- first string in data.strings -->
    <p><span id="crowdin_phrase_index_1" class="crowdin_phrase">Source Text 2</span></p> <!-- second string in data.strings -->
  </body>
</html>