diff --git a/src/content/docs/developer/crowdin-apps/apps-js.mdx b/src/content/docs/developer/crowdin-apps/apps-js.mdx index 0f652900..bbe51589 100644 --- a/src/content/docs/developer/crowdin-apps/apps-js.mdx +++ b/src/content/docs/developer/crowdin-apps/apps-js.mdx @@ -38,6 +38,7 @@ Retrieves a `ContextDataObject` containing key information about the environment **Example:** @@ -70,7 +71,7 @@ AP.getContext(function(contextData) { ##### Response Payload Example -```json collapse={16-25,29-63,66-68} +```json collapse={36-97} { "user_id": 15, "user_login": "john.smith", @@ -78,6 +79,33 @@ AP.getContext(function(contextData) { "project_identifier": "docs-portal", "organization_id": 100001, "organization_domain": "acme", + "user": { + "id": 15, + "username": "john.smith", + "fullname": "John Smith", + "isAdmin": false + }, + "project": { + "id": 123, + "name": "Docs Portal", + "identifier": "docs-portal", + "type": "file-based", + "sourceLanguage": "en", + "targetLanguages": ["fr", "uk"], + "description": "Public documentation portal" + }, + "permissions": [ + { + "name": "translator", + "allLanguages": false, + "languages": ["fr"] + }, + { + "name": "proofreader", + "allLanguages": true, + "languages": [] + } + ], "editor": { "mode": "translate", "theme": "dark", @@ -191,6 +219,134 @@ AP.getContext(function(contextData) {

Description: The domain of the organization the app is installed in (Crowdin Enterprise only).

+ + user + +

Type: object

+

Description: An object containing details of the user the app is displayed to.

+ + + + user.id + +

Type: integer

+

Description: The unique numeric ID of the user.

+ + + + user.username + +

Type: string

+

Description: The username of the user.

+ + + + user.fullname + +

Type: string

+

Description: The full name of the user.

+ + + + user.isAdmin + +

Type: boolean

+

Description: Crowdin Enterprise only. Whether the user has organization administrator + access.

+ + + + project + +

Type: object

+

Description: An object containing details of the project the app is running in. Present when + the app runs in a project context.

+ + + + project.id + +

Type: integer

+

Description: The unique numeric ID of the project.

+ + + + project.name + +

Type: string

+

Description: The display name of the project.

+ + + + project.identifier + +

Type: string

+

Description: The identifier of the project.

+ + + + project.type + +

Type: string

+

Allowed values: file-based, string-based

+ + + + project.sourceLanguage + +

Type: string | null

+

Description: The language code of the project source language.

+ + + + project.targetLanguages + +

Type: array

+

Description: The language codes of the project target languages.

+ + + + project.description + +

Type: string

+

Description: The project description.

+ + + + permissions + +

Type: array

+

Description: The roles the user holds in the current project. Only the highest-level access + is listed, so a user with the admin, owner, manager, or + developer role has no translator, proofreader, or + language_coordinator entry. Present when the app runs in a project context, and empty for a user + with no role in the project.

+ + + + permissions[].name + +

Type: string

+

Allowed values: admin (Crowdin Enterprise only), owner, + manager, developer, language_coordinator, translator, + proofreader

+ + + + permissions[].allLanguages + +

Type: boolean

+

Description: Whether the role covers every target language of the project.

+ + + + permissions[].languages + +

Type: array

+

Description: The language codes the role is limited to. Empty when + allLanguages is true.

+ + editor @@ -347,6 +503,214 @@ AP.getContext(function(contextData) { +#### AP.getPageState(callback) {#get-page-state} + +Retrieves a `PageStateObject` with a snapshot of the current Editor state: everything `AP.getContext()` returns, plus the current string, the string list, translations, filters, and file selection. Use it when your app needs several pieces of state at once, instead of chaining separate `AP.editor.get*` calls. + + + +**Example:** + +```js +AP.getPageState(function(pageState) { + if (pageState) { + console.log("Current string:", pageState.currentString); + console.log("Current page:", pageState.page); + } +}); +``` + +##### Parameters + + + + + + + + +
callback +

Type: function

+

Required: yes

+

Description: A callback function that handles the response. It receives one argument: the PageStateObject or null.

+
+ +##### Response Payload Example + +Objects and arrays below are shortened. See the methods linked in the table for the full structure of +each one. + +```json +{ + // Every field returned by AP.getContext(), plus the fields below + "currentString": { + "id": 1568759, + "text": "Welcome!", + "context": "Main screen" + }, + "stringsList": [ + { + "id": 1568759, + "text": "Welcome!" + } + ], + "selectedStrings": null, + "translations": [], + "topTranslation": null, + "filter": 3, + "customFilter": { + "translations": "untranslated", + "croql_expression": "" + }, + "croqlFilter": "", + "filtersList": [ + { + "name": "Show All", + "value": 3 + } + ], + "page": 1, + "workflowStepStatusFilter": null, + "selectedFiles": [], + "isMultipleFilesSelected": false, + "unsavedSourceStrings": null +} +``` + +##### Response Object Structure + +

The snapshot repeats every field of the AP.getContext response and adds the + fields below.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
currentString +

Type: object | null

+

Description: The currently active source string. See AP.editor.getString for the object structure. null in + asset-based projects.

+
stringsList +

Type: array | null

+

Description: The strings currently visible in the string list. See AP.editor.getStringsList for the object structure. null + in asset-based projects.

+
selectedStrings +

Type: object | null

+

Description: The strings currently selected in the Editor list. See AP.editor.getSelectedStrings for the object structure. + null when no strings are selected, and in translate mode, which has no multiple + selection.

+
translations +

Type: array | null

+

Description: The translations and suggestions for the current string. See AP.editor.getTranslations for the object structure. null + in asset-based projects.

+
topTranslation +

Type: object | null

+

Description: The top translation of the current string. See AP.editor.getTopTranslation for the object structure. + null in asset-based projects and when the string has no translations yet.

+
filter +

Type: integer

+

Description: The numeric ID of the active basic filter. See AP.editor.getFilter.

+
customFilter +

Type: object

+

Description: The current state of the Advanced Filter. See AP.editor.getCustomFilter for the object structure.

+
croqlFilter +

Type: string

+

Description: The active CroQL filter query, or an empty string when no filter is set. See + AP.editor.getCroqlFilter.

+
filtersList +

Type: array

+

Description: The available basic filters, with their names and numeric IDs. See AP.editor.getFiltersList for the object structure.

+
page +

Type: integer

+

Description: The current page number of the string list. See AP.editor.getPage.

+
workflowStepStatusFilter +

Type: string | null

+

Description: Crowdin Enterprise only. The active filter for workflow step status at the + current workflow step, or ALL when no status is selected. See AP.editor.getWorkflowStepStatusFilter for the allowed + values.

+
selectedFiles +

Type: array | null

+

Description: The files selected in the file tree. See AP.editor.getSelectedFiles for the object structure. + null when the Editor has no file tree.

+
isMultipleFilesSelected +

Type: boolean

+

Description: Whether more than one file is selected in the file tree. See AP.editor.isMultipleFilesSelected.

+
unsavedSourceStrings +

Type: object | null

+

Description: The source strings that have unsaved changes. See AP.editor.getUnsavedSourceStrings for the object structure. + null outside multilingual mode.

+
+ #### AP.getTheme(callback) {#get-theme} Retrieves the name of the currently active user interface (UI) theme. @@ -1185,7 +1549,7 @@ These methods allow your app to get information from and perform actions in the ### Data Retrieval (Strings and Files) -This group of methods allows your app to read information about the strings and files currently being viewed in the Editor, as well as change the file selection. +This group of methods allows your app to read information about the strings and files currently being viewed in the Editor, as well as change the file selection. To read several pieces of the Editor state in one call, use [AP.getPageState](#get-page-state). #### AP.editor.getString(callback) {#get-string} @@ -3251,7 +3615,11 @@ This method returns a plain **`string`**. ##### Response Object Structure

Type: string

-

Allowed values: ALL, ToDo, Pending, Done

+

Allowed values: ALL, TODO, PENDING, + INCOMPLETE, DONE

+

PENDING applies to review mode, and INCOMPLETE to + translate, proofread, and multilingual modes. The Editor shows both as + Pending in the Workflow step status menu.

#### AP.editor.setWorkflowStep(stepId) {#set-workflow-step} @@ -3301,7 +3669,11 @@ AP.editor.setWorkflowStepStatusFilter('DONE');

Type: string

Required: Yes

Description: The status to filter by.

-

Allowed values: ALL, TODO, PENDING, DONE

+

Allowed values: ALL, TODO, PENDING, + INCOMPLETE, DONE

+

PENDING applies to review mode, and INCOMPLETE to + translate, proofread, and multilingual modes. The Editor shows both as + Pending in the Workflow step status menu.

@@ -3989,7 +4361,7 @@ AP.project.getTabsConfiguration(function(config) { This method returns an **`array`** of objects. -```json collapse={10-50} +```json collapse={10-49} [ { "identifier": "home", @@ -4711,5 +5083,28 @@ Use these event names with the `AP.events.on()` method to listen for actions hap

Payload: An object containing editor context and suggestion data.

+ + pageState.changed + +

Fires when any part of the Editor page state changes. Changes that happen within 200 ms are reported as a + single event.

+

Payload: The full PageStateObject, plus a changed array naming the + fields that triggered the event. See AP.getPageState for the object + structure. Treat changed as a hint about what to re-read: the payload always carries the latest + state.

+
+ ```json + { + "changed": ["currentString", "translations", "topTranslation"], + "currentString": { + "id": 1568759, + "text": "Welcome!" + }, + "page": 1 + } + ``` +
+ +