From 102563ee64f7993e25a89bc5c11a1b240d34f2a2 Mon Sep 17 00:00:00 2001
From: Mykhailo Rohalskyy <mykhailo.rohalskyy@crowdin.ua>
Date: Thu, 6 Aug 2026 18:51:17 +0300
Subject: [PATCH] docs(developer): polish the Workflow Step Type articles

- align the string status examples with the webhook payload example
- quote the real workflow validation messages in the Enterprise article
- use "strings" instead of "segments" and spell out "for example"
- drop "allows you to" from the module intro and fix stray typography
---
 .../modules/other/workflow-step-type.mdx      | 24 +++++++++----------
 .../workflows/app-based-workflow-step.mdx     | 20 ++++++++--------
 2 files changed, 22 insertions(+), 22 deletions(-)

diff --git a/src/content/docs/developer/modules/other/workflow-step-type.mdx b/src/content/docs/developer/modules/other/workflow-step-type.mdx
index bd8f5152..46324ef3 100644
--- a/src/content/docs/developer/modules/other/workflow-step-type.mdx
+++ b/src/content/docs/developer/modules/other/workflow-step-type.mdx
@@ -10,7 +10,7 @@ sidebar:
 import { Steps, Aside } from '@astrojs/starlight/components';
 import ReadMore from '~/components/ReadMore.astro';
 
-This module allows you to create custom workflow step types to extend the default list of workflow steps in Crowdin Enterprise. With this app installed, the new workflow step types become available in the workflow editor, where they can be added to workflows and templates, enabling greater customization and flexibility.
+With this module you can create custom workflow step types that extend the default list of workflow steps in Crowdin Enterprise. Once the app is installed, the new step types become available in the workflow editor, where they can be added to workflows and templates.
 
 A custom workflow step is an external processing stage in a workflow. Crowdin Enterprise routes the strings, tracks their status, and counts progress, while your app implements the step's condition of done: it decides when a string is complete on the step and which output it leaves through. Typical uses include AI-based review, integration with an external review or MT system, compliance gates, and delay or scheduling steps.
 
@@ -437,7 +437,7 @@ The Workflow Step Type module relies on webhooks and API methods to communicate
 
 Crowdin Enterprise sends a batched webhook payload to the app's Webhook module whenever strings reach a custom workflow step provided by the app. When a string lands on the custom step (for example, it was just added, moved there by a previous step, or re-triggered), its status on the step becomes **Need Process** and the webhook event is queued for delivery.
 
-This payload contains the `string.status_on_step.recalculation_triggered` event and includes all relevant strings that need external processing (e.g., AI-based proofreading).
+This payload contains the `string.status_on_step.recalculation_triggered` event and includes all relevant strings that need external processing (for example, AI-based proofreading).
 
 <Aside>
   Webhook events are delivered in batches and may arrive with a short delay. Respond with a `2xx` status code as quickly as possible and process the strings asynchronously. Read more about [Delivery Guarantees](#delivery-guarantees-and-reconciliation).
@@ -614,7 +614,7 @@ Below are the API methods for managing string statuses on a custom workflow step
         <td><code>organization_domain</code></td>
         <td>Yes</td>
         <td><code>string</code></td>
-        <td>Your Crowdin Enterprise organization’s domain.</td>
+        <td>Your Crowdin Enterprise organization's domain.</td>
       </tr>
       <tr>
         <td><code>projectId</code></td>
@@ -665,8 +665,8 @@ Below are the API methods for managing string statuses on a custom workflow step
       {
         "data": {
           "stringId": 1106423,
-          "languageId": "uk",
-          "stepId": 889,
+          "languageId": "et",
+          "stepId": 1035,
           "status": "DONE",
           "output": "translated"
         }
@@ -674,8 +674,8 @@ Below are the API methods for managing string statuses on a custom workflow step
       {
         "data": {
           "stringId": 1106430,
-          "languageId": "uk",
-          "stepId": 889,
+          "languageId": "et",
+          "stepId": 1035,
           "status": "DONE",
           "output": "untranslated"
         }
@@ -708,7 +708,7 @@ Below are the API methods for managing string statuses on a custom workflow step
         <td><code>organization_domain</code></td>
         <td>Yes</td>
         <td><code>string</code></td>
-        <td>Your Crowdin Enterprise organization’s domain.</td>
+        <td>Your Crowdin Enterprise organization's domain.</td>
       </tr>
       <tr>
         <td><code>projectId</code></td>
@@ -777,8 +777,8 @@ Below are the API methods for managing string statuses on a custom workflow step
       {
         "data": {
           "stringId": 1106423,
-          "languageId": "uk",
-          "stepId": 889,
+          "languageId": "et",
+          "stepId": 1035,
           "status": "DONE",
           "output": "translated"
         }
@@ -786,8 +786,8 @@ Below are the API methods for managing string statuses on a custom workflow step
       {
         "data": {
           "stringId": 1106430,
-          "languageId": "uk",
-          "stepId": 889,
+          "languageId": "et",
+          "stepId": 1035,
           "status": "DONE",
           "output": "untranslated"
         }
diff --git a/src/content/docs/enterprise/organization-management/workflows/app-based-workflow-step.mdx b/src/content/docs/enterprise/organization-management/workflows/app-based-workflow-step.mdx
index 3bea6818..c78f610e 100644
--- a/src/content/docs/enterprise/organization-management/workflows/app-based-workflow-step.mdx
+++ b/src/content/docs/enterprise/organization-management/workflows/app-based-workflow-step.mdx
@@ -20,11 +20,11 @@ Unlike built-in steps, an app-based step defines its own completion rules: the a
 
 Below are a few examples of how app-based steps can enhance your workflows. Some are drawn from existing Crowdin Store apps, while others illustrate broader possibilities:
 
-* **Workflow Delay** – The [Workflow Delay](https://store.crowdin.com/workflow-step-delay) app adds checkpoint-style steps that pause segments until conditions are met or on a set schedule. This helps prevent incomplete or unverified segments from moving forward prematurely, improving overall translation consistency.
+* **Workflow Delay** – The [Workflow Delay](https://store.crowdin.com/workflow-step-delay) app adds checkpoint-style steps that pause strings until conditions are met or on a set schedule. This helps prevent incomplete or unverified strings from moving forward prematurely, improving overall translation consistency.
 
 * **AI Source Review** – Another possible scenario could be an app that automatically reviews and refines source text before translation, catching typos, style inconsistencies, or placeholders that might cause issues later. This approach helps ensure higher-quality translations by starting with well-polished source strings.
 
-* **AI Labeling** – A step that could analyze your strings and automatically apply labels (e.g., “Marketing Content,” “Technical Doc,” “High Priority”), helping route content to the most appropriate translation or review paths.
+* **AI Labeling** – A step that could analyze your strings and automatically apply labels (for example, "Marketing Content", "Technical Doc", "High Priority"), helping route content to the most appropriate translation or review paths.
 
 <CardGrid>
   <LinkCard
@@ -45,7 +45,7 @@ Before you can add an app-based workflow step, you need to install the correspon
   Read more about [Creating Workflow Step Apps](/developer/crowdin-apps-module-workflow-step-type/).
 </ReadMore>
 
-Depending on the app, you may need specific permissions (e.g., Manager or Admin) to install it. Once installed, the new step types appear in your workflow editor or workflow template editor.
+Depending on the app, you may need specific permissions (for example, Manager or Admin) to install it. Once installed, the new step types appear in your workflow editor or workflow template editor.
 
 <ReadMore>
   Read more about [Installing Crowdin Apps](/developer/crowdin-apps-installation/#installation-in-crowdin-enterprise).
@@ -76,16 +76,16 @@ You can add app-based workflow steps directly to a project's workflow in the wor
 
 Depending on how the app is implemented, an app-based workflow step may offer various configuration options, or none at all. For example:
 
-* **Configurable Steps** – Some steps allow you to adjust parameters in the workflow editor (e.g., specifying a delay for content processing). In these cases, you can modify the available options to suit your needs.
+* **Configurable Steps** – Some steps allow you to adjust parameters in the workflow editor (for example, specifying a delay for content processing). In these cases, you can modify the available options to suit your needs.
 
-* **Pre-configured Steps** – Other steps have all their settings predefined by the app (e.g., delaying content until an entire file is fully translated), so no additional fields appear in the workflow editor.
+* **Pre-configured Steps** – Other steps have all their settings predefined by the app (for example, delaying content until an entire file is fully translated), so no additional fields appear in the workflow editor.
 
 If a step provides configuration fields, they typically appear in the step's settings panel once you drag it into the workflow.
 
-These fields can include anything from AI prompts and allowed actions (e.g., approving or deleting translations, adding translation suggestions or comments, etc.) to API tokens, delay intervals, or match conditions — whatever the app developer has enabled. If there are no visible configuration options, the app likely manages all necessary setup internally.
+These fields can include anything from AI prompts and allowed actions (for example, approving or deleting translations, adding translation suggestions or comments) to API tokens, delay intervals, or match conditions, whatever the app developer has enabled. If there are no visible configuration options, the app likely manages all necessary setup internally.
 
 <Aside type="tip">
-  We recommend to always explore the app's documentation for details on any available settings it may provide.
+  Explore the app's documentation for details on the settings it provides.
 </Aside>
 
 ## Troubleshooting
@@ -94,10 +94,10 @@ When an app-based step is misconfigured, Crowdin Enterprise flags the workflow a
 
 * **Error Banners and Inactive Steps** – If the app is removed or becomes inactive, your project's Dashboard may display a banner informing about the workflow issues with instructions on how to resolve them.
   <Image src={workflowIssuesBanner} alt="Workflow Issues Banner" />
-  In the workflow editor, you may see steps with failed validations (e.g., *The application required for this step type is uninstalled*). To fix this, reinstall the app and reconfigure its step, or remove the step if it's no longer needed.
-* **Validation Warnings** – When saving changes to the workflow, a warning might appear if the app-based step is misconfigured or has unmet dependencies (e.g., *Workflow Delay Agent requires manager permissions*). Such a warning usually means that the app's [bot user](#bot-user) lost manager access to the project – re-add the bot to the project members with the Manager role.
+  In the workflow editor, you may see steps with failed validations (for example, *The application required for this step type is uninstalled or not allowed for the project*). To fix this, reinstall the app and reconfigure its step, or remove the step if it's no longer needed.
+* **Validation Warnings** – When saving changes to the workflow, a warning might appear if the app-based step is misconfigured or has unmet dependencies (for example, *"Workflow Delay Agent" requires manager permissions for the project*). Such a warning usually means that the app's [bot user](#bot-user) lost manager access to the project – re-add the bot to the project members with the Manager role.
 * **Failed Strings on the Step** – If the app couldn't be notified about strings that reached its step (for example, the app's service was temporarily unavailable), those strings are counted as failed words on the step. The step then shows a warning with the number of failed words. Once the app is available again, a project manager can click **Resend** on the step to send those strings to the app again.
-* **No Access to the App-based Step** – Occasionally, an app-based step may not appear in the workflow editor if the app was installed with limited project access or if you lack the required role (e.g., Manager). Check your project settings to confirm you have Manager or Admin rights and that the app is allowed in the intended project.
+* **No Access to the App-based Step** – Occasionally, an app-based step may not appear in the workflow editor if the app was installed with limited project access or if you lack the required role (for example, Manager). Check your project settings to confirm you have Manager or Admin rights and that the app is allowed in the intended project.
 * **Connectivity or External Service Errors** – If an app-based step relies on a third-party service or API, timeouts or network failures may cause the step to fail or get stuck.
   * **Check Service Status**: Verify that any external service used by the app is online and functioning properly.
   * **Inspect Logs**: If the app provides logs or an admin panel, review any error messages it may have generated.