Translation Alignment Processing Module

The Translation Alignment Processing module allows you to override Crowdin’s default alignment mechanism when uploading translations for non-key-value files (e.g., HTML, MD).

By default, Crowdin automatically aligns uploaded translations with existing source strings. When you use this module in your Crowdin app, you can intercept this process and apply your own custom alignment logic, for example, by using a third-party alignment service. This gives you full control over how translations are mapped to their corresponding source strings for complex document formats.

Access

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

For Crowdin:

Only me (i.e., project owner)
Me, project managers and developers
Selected users

For Crowdin Enterprise:

Only organization admins
Organization admins, project managers and developers
Selected users

Structure

{
  "modules": {
    "file-translations-alignment": [
      {
        "key": "your-translations-alignment-module-key",
        "url": "/translations-alignment",
        "signaturePatterns": {
          "fileName": "^.+\\.html$",
          "fileContent": "<html.*>"
        }
      }
    ]
  }
}

Properties

key

Type: string

Required: yes

Description: Module identifier within the Crowdin app.

url

Type: string

Required: yes

Description: The relative URL triggered on translation upload.

signaturePatterns

Type: object

Description: Contains fileName and/or fileContent regular expressions used to detect file type when uploading translations via UI (or via API without specified type parameter).

Communication between Translation Alignment App and Crowdin

When uploading a translation file for a non-key-value format, the system detects an appropriate translation alignment module using the signaturePatterns parameter. Crowdin then makes an HTTP request to the app’s URL ($baseUrl . $url).

This request contains two main arrays: sourceStrings (from the project) and translationStrings (parsed from the uploaded translation file). The app’s job is to process these two sets of strings, perform the alignment, and return a structured response that maps the translations to their correct source string identifiers.

Request to the Translation Alignment App

Request payload example:

// max request payload - 5 MB
// wait timeout - 2 minutes
{
  "jobType": "translation-alignment-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",
    "userId": 1,
    "sourceLanguageId": "en",
    "targetLanguageIds": [
      "ja",
      "uk",
      "et"
    ],
    "createdAt": "2030-01-15T07:00:00+00:00",
    "updatedAt": "2030-01-15T07:00:15+00:00",
    "lastActivity": "2030-01-15T10:12:13+00:00",
    "description": null,
    "url": "/project/your-project-identifier",
    "cname": null
  },
  "sourceLanguage": {
    "id": "en",
    "name": "English",
    "editorCode": "en",
    "twoLettersCode": "en",
    "threeLettersCode": "eng",
    "locale": "en-US",
    "androidCode": "en-rUS",
    "osxCode": "en.lproj",
    "osxLocale": "en",
    "pluralCategoryNames": [
      "one",
      "other"
    ],
    "pluralRules": "(n != 1)",
    "pluralExamples": [
      "1",
      "0, 2-999; 1.2, 2.07..."
    ],
    "textDirection": "ltr",
    "dialectOf": null
  },
  "targetLanguages": [
    {
      // Language object for the translation being aligned. Has the same structure as sourceLanguage.
    }
  ],
  "file": {
    "id": 4219,
    "name": "en.html",
    "title": null,
    "path": "/en.html",
    "type": "html32",
    "isMultilingual": false,
    "status": "active",
    "revision": 1,
    "branchId": null,
    "directoryId": 0
  },
  "sourceStrings": [
    {
      "id": 1234567,
      "text": "Welcome!",
      "context": "Document Title\\r\\nXPath: \\/html\\/head\\/title"
    }
    // other source strings ...
  ],
  "translationStrings": [
    {
      "id": null,
      "text": "Ласкаво просимо!",
      "context": "Document Title\\r\\nXPath: \\/html\\/head\\/title"
    }
    // other translation strings ...
  ]
}

Properties:

`jobType`	Type: `string` Value: `translation-alignment-file` Description: Specifies the action of the translation alignment module.
`file`	Type: `object` Description: Contains information about the source file in Crowdin to which the translations are being uploaded.
`targetLanguages`	Type: `array` Description: An array containing the language object of the translation file being uploaded and aligned.
`sourceStrings`, `sourceStringsUrl`	Type(sourceStrings): `array` Type(sourceStringsUrl): `string` Description: Parameters used for source strings from the original file. `sourceStrings` - array of source string objects. `sourceStringsUrl` - public URL to a new-line delimited json with source strings. Either of these two parameters can be used. Maximum request payload limit is 5 MB.
`translationStrings`, `translationStringsUrl`	Type(translationStrings): `array` Type(translationStringsUrl): `string` Description: Parameters used for strings parsed from the uploaded translation file. `translationStrings` - array of simple string objects. `translationStringsUrl` - public URL to a new-line delimited json with translation strings. Either of these two parameters can be used. Maximum request payload limit is 5 MB.

Expected Response from the App

The app must perform its custom alignment and return a response containing a translations array. This array maps each translation text to its corresponding sourceStringId.

Response payload example:

// max response payload - 5 MB
// wait timeout - 2 minutes
{
  "data": {
    "translations": [
      {
        "sourceStringId": 1234567,
        "text": "Ласкаво просимо!"
      },
      // other translation mappings...
    ],
    // or use translationsUrl for large payloads
    "translationsUrl": "https://app.example.com/jKe8ujs7a-aligned.ndjson" // new-line delimited json file with aligned translations
  },
  "error": {
    "message": "Optional error message"
  }
}

Properties:

`data.translations`, `data.translationsUrl`	Type(data.translations): `array` Type(data.translationsUrl): `string` Description: Parameters used to pass the aligned translations. `data.translations` - array of alignment objects. `data.translationsUrl` - public URL to a new-line delimited json with alignment objects. Either of these two parameters can be used. Maximum response payload limit is 5 MB.
`data.translations.sourceStringId`	Type: `integer` Description: The numeric identifier of the source string to which the translation should be applied.
`data.translations.text`	Type: `string` or `object` Description: The translation text to be applied. For plural strings, this must be an object keyed by the target language’s plural category names (e.g., `one`, `other`).
`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.

Was this page helpful?