Skip to content

Crowdin Apps JS

The Crowdin Apps JS is a library built for easier interaction with Crowdin. Since the integration uses the iframes, there are certain limitations on the interaction between windows: environments are encapsulated and do not have access to the page content, code, styles, and any other information related to the page.

The Crowdin Apps JS library is based on cross-window messaging technology and uses postMessage() to interact between multiple windows.

Getting Started

To use this library, connect it on the module page by inserting the following code into the page header:

<script src="https://cdn.crowdin.com/apps/dist/iframe.js"></script>

After adding the code mentioned above, you’ll be able to use the global AP variable.

Global Actions

Global actions are the actions that are available on all module pages.

AP.getContext(callback)

The method retrieves the context information about the current page and puts it into the callback. For example, the project ID where the module is opened or the locale used on the page.

Example:

AP.getContext(function(contextData) {
console.log("Object: context", contextData);
});

Properties:

callback

Type: function

Description: The callback that handles the response object.

Depending on the current page on which this method is used, the payload may contain a different set of the context information.

Payload example:

{
"project_id": "12",
"organization_id": "200000000",
"editor": {
"mode": "translate",
"theme": "dark",
"source_language_id": "en",
"target_language_id": "fr",
"file": 12345,
"workflow_step": {
"id": 7777,
"title": "Translation",
"type": "Translate"
}
}
}

Properties:

project_id

Type: string

Description: The identifier of the Crowdin project.

organization_id

Type: string

Description: Crowdin Enterprise only. The identifier of the organization in Crowdin Enterprise.

editor

Type: object

Description: Contains settings and context for the Editor.

editor.mode

Type: string

Description: Active mode of the Editor.

editor.theme

Type: string

Description: Active theme of the Editor.

editor.source_language_id

Type: string

Description: The identifier of the source language.

editor.target_language_id

Type: string

Description: The identifier of the target language.

editor.file

Type: integer

Description: The numeric identifier of a file in the Crowdin project that is open in the Editor.

editor.workflow_step

Type: object

Description: Crowdin Enterprise only. Details of the current workflow step in the Editor.

editor.workflow_step.id

Type: integer

Description: The numeric identifier of the workflow step.

editor.workflow_step.title

Type: string

Description: Title of the workflow step.

editor.workflow_step.type

Type: string

Description: Type of the workflow step.

AP.getJwtToken(callback)

The method retrieves a JWT token string. Used to get a current token. If the previous token has a validity period of less than one minute, the method will generate and return a new token.

Example:

AP.getJwtToken(function(jwtToken) {
console.log("String: JWT token", jwtToken);
});

Properties:

callback

Type: function

Description: The callback that handles the response string.

AP.getTheme()

The method retrieves information about the currently selected theme.

Example:

AP.getTheme(function(theme) {
light | dark
});

Properties:

callback

Type: function

Description: The callback that handles the response string.

Editor Module Actions

Editor module actions provide a possibility to get information from the Editor UI. These actions are available only on pages that are loaded in an iframe in the Editor-panels module.

AP.editor.getString(callback)

The method retrieves information about the currently selected string in the Editor.

Example:

AP.editor.getString(function(stringData) {
console.log("Object: source string", stringData);
});

Properties:

callback

Type: function

Description: The callback that handles the response object.

AP.editor.getTranslations(callback)

The method retrieves a list of translations suggested to the currently selected string in the Editor. Additionally, the response contains information about the translation author, the number of votes, and approval on the current workflow step.

Example:

AP.editor.getTranslations(function(translationsData) {
console.log("Array: translation objects", translationsData);
});

Properties:

callback

Type: function

Description: The callback that handles the response array.

AP.editor.getTopTranslation(callback)

The method retrieves a top translation (the translation with the highest priority) for the currently selected source string in the Editor.

Example:

AP.editor.getTopTranslation(function(topTranslationData) {
console.log("Object: top translation", topTranslationData);
});

Properties:

callback

Type: function

Description: The callback that handles the response object.

AP.editor.setTranslation(text)

The method sets the translation text for the currently selected source string in the Editor.

Example:

AP.editor.setTranslation("Hello,");

Properties:

text

Type: string

Description: The translation text that is being set for the currently selected source string.

AP.editor.appendTranslation(text)

The method appends the translation text next to the cursor for the currently selected source string in the Editor.

Example:

AP.editor.appendTranslation(" {user},");

Properties:

text

Type: string

Description: The translation text that is being appended next to the cursor for the currently selected source string.

AP.editor.clearTranslation()

The method clears the translation text for the currently selected source string in the Editor.

Example:

AP.editor.clearTranslation();

AP.editor.setFocus()

The method sets focus on the translation field in the Editor.

Example:

AP.editor.setFocus();

AP.editor.noticeMessage(message)

The method displays the notice message text in the Editor.

Example:

AP.editor.noticeMessage("Message text");

Properties:

text

Type: string

Description: The notice message text that is being displayed.

AP.editor.successMessage(message)

The method displays the success message text in the Editor.

Example:

AP.editor.successMessage("Message text");

Properties:

text

Type: string

Description: The success message text that is being displayed.

AP.editor.errorMessage(message)

The method displays the error message text in the Editor.

Example:

AP.editor.errorMessage("Message text");

Properties:

text

Type: string

Description: The error message text that is being displayed.

AP.editor.setApplicationNotification(1)

The method sets a notification count next to an app icon in the right panel in the Editor.

Example:

AP.editor.setApplicationNotification(1);

Properties:

count

Type: integer

Description: The notification count number.

AP.editor.clearApplicationNotification()

The method clears a notification count next to an app icon in the right panel in the Editor.

Example:

AP.editor.clearApplicationNotification();

AP.editor.getCustomFilter(callback)

The method retrieves the current Advanced filter applied in the Editor.

Example:

AP.editor.getCustomFilter(function(customFilter) {
console.log(customFilter);
});

Properties:

callback

Type: function

Description: The callback that handles the custom filter object.

AP.editor.setCustomFilter(customFilter)

The method sets a Advanced filter in the Editor.

Example:

AP.editor.setCustomFilter({
//filter object
});

Properties:

customFilter

Type: object

Description: The custom filter object to be applied.

AP.editor.resetCustomFilter()

The method resets the Advanced filter to the default state.

Example:

AP.editor.resetCustomFilter();

AP.editor.getFilter(callback)

The method retrieves the current filter applied in the Editor.

Example:

AP.editor.getFilter(function(filter) {
console.log(filter);
});

Properties:

callback

Type: function

Description: The callback that handles the filter ID.

AP.editor.setFilter(filterNumber)

The method sets a filter in the Editor.

Example:

AP.editor.setFilter(filterNumber);

Properties:

filterNumber

Type: integer

Description: The filter ID to be applied.

Filter Option IDs:

  • All, Untranslated First – 0
  • Untranslated – 2
  • Show All – 3
  • Approved – 4
  • Translated, Not Approved – 5
  • Hidden – 6
  • With Comments – 7
  • Unsaved translations – 39
  • Translated by TM – 30
  • Translated by MT – 31
  • Translated by TM or MT – 10
  • Advanced Filter – 12
  • With unresolved issues (All languages) – 13
  • Need to be voted – 15
  • Without comments – 16
  • With unresolved issues (Current language) – 17
  • QA Issues (All) – 18
  • QA Issues (Empty translation) – 19
  • QA Issues (Variables mismatch) – 20
  • QA Issues (Tags mismatch) – 21
  • QA Issues (Punctuation mismatch) – 22
  • QA Issues (Character case mismatch) – 23
  • QA Issues (Spaces mismatch) – 24
  • QA Issues (Length issues) – 25
  • QA Issues (Special character mismatch) – 26
  • QA Issues (“Incorrect translation” issues) – 27
  • QA Issues (Spelling) – 28
  • QA Issues (ICU syntax) – 29
  • QA Issues (Consistent terminology) – 32
  • QA Issues (Without QA issues) – 33
  • QA Issues (Duplicate translation) – 35
  • QA Issues (FTL syntax) – 36
  • QA Issues (Android syntax) – 37

AP.editor.getFiltersList(filters)

The method retrieves the list of available filter options in the Editor.

Example:

AP.editor.getFiltersList(function(filters) {
console.log(filters);
});

Properties:

callback

Type: function

Description: The callback that handles the filters object.

AP.editor.getPage(callback)

The method retrieves the current page number in the Editor.

Example:

AP.editor.getPage(function(page) {
console.log(page);
});

Properties:

callback

Type: function

Description: The callback that handles the page number.

AP.editor.setPage(pageNumber)

The method sets a page number in the Editor.

Example:

AP.editor.setPage(pageNumber);

Properties:

pageNumber

Type: integer

Description: The page number to be set.

AP.editor.getProjectTargetLanguages(callback)

The method retrieves the target languages for the current project.

Example:

AP.editor.getProjectTargetLanguages(function(languages) {
console.log(languages);
});

Properties:

callback

Type: function

Description: The callback that handles the target languages array.

AP.editor.setTargetLanguage(languageIdOrIds, callback)

The method sets the target language(s) in the Editor.

Example:

AP.editor.setTargetLanguage(languageId | languageIds, function(res) {
console.log(res)// response message
});

Properties:

languageIdOrIds

Type: string | array

Description: The ID or array of IDs of the target languages to be set.

callback

Type: function

Description: The callback that handles the response.

AP.editor.getCroqlFilter(callback)

The method retrieves the current CroQL filter applied in the Editor.

Example:

AP.editor.getCroqlFilter(function(croql) {
console.log(croql);
});

Properties:

callback

Type: function

Description: The callback that handles the CroQL.

AP.editor.setCroqlFilter(croql)

The method sets a CroQL filter in the Editor.

Example:

AP.editor.setCroqlFilter(croql);

Properties:

croql

Type: string

Description: The CroQL filter to be applied.

AP.editor.resetCroqlFilter()

The method resets the CroQL filter to the default state.

Example:

AP.editor.resetCroqlFilter();

The method performs a search within the Editor.

Example:

AP.editor.search('text', {
searchStrict: false,
searchFullMatch: false,
caseSensitive: false,
search_option: 0 // 1 - Strings, 2 - Context, 3 - Translations, 4 - Identifier (Key), 0 - Everything
});

Properties:

text

Type: string

Description: The search text.

options

Type: object

Description: The search options.

AP.editor.setWorkflowStepStatusFilter(status)

The method sets a workflow step status filter in the Editor (Crowdin Enterprise only).

Example:

AP.editor.setWorkflowStepStatusFilter('ALL' | 'TODO' | 'DONE' | 'INCOMPLETE');

Properties:

status

Type: string

Description: The workflow step status to be set.

AP.editor.getWorkflowStepStatusFilter(callback)

The method retrieves the current workflow step status filter applied in the Editor.

Example:

AP.editor.getWorkflowStepStatusFilter(function(step) {
console.log(step);
});

Properties:

callback

Type: function

Description: The callback that handles the workflow step status filter.

AP.editor.getMode(callback)

The method retrieves the current mode of the Editor.

Example:

AP.editor.getMode(function(mode) {
console.log(mode);
});

Properties:

callback

Type: function

Description: The callback that handles the current mode.

AP.editor.setMode(mode)

The method sets a mode in the Editor.

Example:

AP.editor.setMode('translate' | 'proofread' | 'review' | 'multilingual');

Properties:

mode

Type: string

Description: The mode to be set.

Event Module Actions

Event module actions provide a possibility to work with events, enable the Crowdin app to respond to events that happen in Crowdin UI, and trigger its own events. Read more about supported events.

AP.events.once(event, callback)

The method subscribes a one-time listener to detect events with a specified name. The listener is unsubscribed as soon as the first event is processed.

Example:

AP.events.once("event", function(eventData) {
console.log("Event data", eventData);
});

Properties:

event

Type: string

Description: The name of the event the callback of the function should react to.

callback

Type: function

Description: The callback that handles the event. Depending on the event’s type, there could be either one or a few arguments in the callback.

AP.events.on(event, callback)

The method subscribes a listener to all events with a specified name.

Example:

AP.events.on("event", function(eventData) {
console.log("Event data", eventData);
});

Properties:

event

Type: string

Description: The name of the event the callback of the function should react to.

callback

Type: function

Description: The callback that handles the event. Depending on the event’s type, there could be either one or a few arguments in the callback.

AP.events.off(event, callback)

The method unsubscribes a listener for an event with a specified name.

Example:

function callback(eventData) {
console.log("Event data", eventData);
};
AP.events.on("event", callback);
AP.events.off("event", callback);

Properties:

event

Type: string

Description: The name of the event the callback of the function should be unsubscribed from.

callback

Type: function

Description: The callback that was previously subscribed to the event.

AP.events.ofAll(event)

The method unsubscribes all previously subscribed listeners from the specified event.

Example:

AP.events.offAll("event");
event

Type: string

Description: The name of the event all listeners should be unsubscribed from.

AP.events.onAny(callback)

The method subscribes to all events from Crowdin UI.

Example:

AP.events.onAny(function(event, data) {
console.log("Event name string", event);
console.log("Event data", data);
});

Properties:

callback

Type: function

Description: The callback that receives the name of the event and all the data transferred to the event.

AP.events.offAny(callback)

The method unsubscribes a listener from all events.

Example:

function callback(event, data) {
console.log("Event name string", event);
console.log("Event data", data);
};
AP.events.onAny(callback);
AP.events.offAny(callback);

Properties:

callback

Type: function

Description: The callback that was subscribed to all events.

Supported Events

Check out the list of supported events that could be passed to the Crowdin Apps JS library in the following table:

EventDetails
string.change

The event emitted when a user switches from one string to another.

{
"id": 3939912,
"text": "source string",
"context": "string context",
"max_length": 35,
"file": {
"id": 26588,
"name": "file name.csv"
}
}
textarea.edited

The event emitted when a user performs any changes in the translation field.

{
"id": 3939912,
"text": "source string",
"context": "string context",
"max_length": 0,
"file": {
"id": 26588,
"name": "file name.csv"
},
"oldText": "chaîne de caractères source",
"newText": "chaîne source"
}
translation.added

The event emitted when a user saves a translation for the current string.

{
"id": 422648,
"string_id": 3939912,
"text": "chaîne source",
"target_language_id": "fr",
"votes_rating": 0,
"approved": false,
"author": {
"id": "1",
"login": "user.login",
"name": "User Name",
"avatar_url": "https://avatar.com/avatar.png"
},
"created_at": "2022-12-09T12:17:37-05:00"
}
translation.deleted

The event emitted when a user deletes a translation.

{
"id": 422560,
"string_id": 3939912
}
translation.restored

The event emitted when a user restores a deleted translation.

{
"id": 422648,
"string_id": 3939912,
"text": "chaîne source",
"target_language_id": "fr",
"“votes_rating”": 0,
"author": {
"id": "1",
"login": "user.login",
"name": "User Name",
"avatar_url": "https://avatar.com/avatar.png"
},
"created_at": "2022-12-09T12:17:37-05:00"
}
translation.vote

The event emitted when a user votes for a translation.

{
"id": 422648,
"string_id": 3939912,
"text": "chaîne source",
"target_language_id": "fr",
"votes_rating": 1,
"approved": false,
"author": {
"id": "1",
"login": "user.login",
"name": "User Name",
"avatar_url": "https://avatar.com/avatar.png"
},
"created_at": "2022-12-09T12:17:37-05:00"
}
translation.approve

The event emitted when a user approves a translation.

{
"id": 422648,
"string_id": 3939912,
"text": "chaîne source",
"target_language_id": "fr",
"votes_rating": 0,
"approved": true,
"author": {
"id": "1",
"login": "user.login",
"name": "User Name",
"avatar_url": "https://avatar.com/avatar.png"
},
"created_at": "2022-12-09T12:17:37-05:00",
"approver": {
"id": "1",
"login": "super.user",
"name": "Super User",
"avatar_url": "https://avatar.com/avatar.png"
},
"approved_at": "2022-12-09T17:20:28.655Z"
}
translation.disapprove

The event emitted when a user removes a translation approval.

{
"id": 422406,
"string_id": 3939858,
"text": "chaîne de caractères source",
"target_language_id": "fr",
"votes_rating": 0,
"approved": false,
"author": {
"id": "1",
"login": "user.login",
"name": "User Name",
"avatar_url": "https://avatar.com/avatar.png"
},
"created_at": "2022-12-08T12:29:07-05:00"
}
language.change

The event emitted when a user changes a target language in the Editor.

{
"project_id": "15",
"organization_id": "200000000",
"editor": {
"mode": "translate",
"theme": "dark;",
"source_language_id": "en",
"target_language_id": "fr",
"file": 26588,
"workflow_step": {
"id": 77,
"title": "Translation",
"type": "Translate"
}
}
}
file.change

The event emitted when a user changes a file in the Editor.

{
"project_id": "15",
"organization_id": "200000000",
"editor": {
"mode": "translate",
"theme": "dark;",
"source_language_id": "en",
"target_language_id": "fr",
"file": 26574,
"workflow_step": {
"id": 77,
"title": "Translation",
"type": "Translate"
}
}
}
theme.changed

The event emitted when a user switches from one theme to another.

"light"
Was this page helpful?