> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://contentful.com/developers/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://contentful.com/_mcp/server.

# Localized workflows

> **Info**
>
> Only organization or space admins can create a localized workflow definition.

Localized workflows introduce two new concepts:

* **Variables**: placeholders for actors (users or teams) and locales.

* **Variable value presets**: named sets of variable values that define actor–locale pairings.

When you enable localization for a workflow in the workflow configuration page, the system automatically creates two variables:

* `translator` (type: `subject`)

* `locale` (type: `locale`)

Each translator–locale pairing configured in the Localization settings corresponds to a `variableValuePreset`. These presets ensure that workflow permissions can adapt dynamically depending on the language and translator assigned.

A localized workflow must have at least one of these pairings.

> **Info**
>
> Creating a workflow for a given preset (known as `locale` in the frontend), you **cannot** delete the configuration for that preset as long as that workflow is active. A maximum of 3 steps can rely on variables.

## Create a localized workflow definition

[Create a localized workflow definition](/references/content-management-api/workflow-definitions/create-a-workflow-definition)

Creates a new workflow definition with optional variables and variable value presets.

**Key points**

* **Variables** are defined in the `appliesTo[].variables` array.

* **Variable value presets** are defined in the `appliesTo[].variableValuePresets` array.

* Each preset must provide values for **all** variables defined in the workflow definition.

* Variables can be referenced in step permissions using `WorkflowVariable` links.

**Variable types:**

* `subject`: Used for `actors` in permissions, values must be User or Team links
* `locale`: Used for `locale` in permissions, values are locale strings (e.g., "de-DE")

## Update a localized workflow definition

[Update a localized workflow definition](/references/content-management-api/workflow-definitions/update-a-workflow-definition)

Updates an existing workflow definition. Variable and preset modifications have restrictions.

**Variable and preset update rules:**

* **Cannot** change variable types once defined.

* **Cannot** add variables if the definition previously had none.

* **Cannot** remove variables from existing definitions.

* **Cannot** remove all presets if variables are defined.

* **Can** add new presets to existing definitions.

* **Cannot** remove presets that are currently used by active workflows.

## Create a localized workflow instance

[Create a localized workflow instance](/references/content-management-api/workflows/create-a-workflow)

Creates a localized workflow instance, optionally specifying a variable value preset.

**Behavior with variables**

* If the workflow definition has variables and presets, you **must** provide a `variableValuePreset`.

* The specified preset determines the actual values for variables used in permissions.

* The preset ID must match one of the presets defined in the workflow definition.

* Automatic workflow start is **disabled** when variables and presets are present.

## WorkflowSteps.permissions with variables

#### Permission structure

Permissions can reference variables in two places:

1. Actors (for subject variables)

```
{
  "type": "entity_permission",
  "configuration": {
    "action": "edit",
    "effect": "allow",
    "actors": [
      {
        "sys": {
          "type": "Link",
          "linkType": "WorkflowVariable",
          "id": "translator-variable-id"
        }
      }
    ]
  }
}
```

2. Locale (for locale variables)

```
{
  "type": "entity_permission",
  "configuration": {
    "action": "edit",
    "effect": "allow",
    "actors": ["all"],
    "locale": {
      "sys": {
        "type": "Link",
        "linkType": "WorkflowVariable",
        "id": "locale-variable-id"
      }
    }
  }
}
```

## Validation rules

#### Variables

* Variable IDs must be unique within a workflow definition.
* Variable types (`subject` or `locale`) cannot be changed after creation.
* Variables cannot be added to or removed from existing workflow definitions.

#### Variable value presets

* Maximum of 80 presets per workflow definition.

* Each preset must provide values for **all** variables defined in the workflow definition.

* Preset IDs must be unique within a workflow definition.

* Values must match variable types:

  * `subject` variables: User or Team links

  * `locale` variables: Locale strings (e.g., "en-US", "de-DE")

## Errors

* `422 Validation Error`: Missing preset values or invalid variable types.
* `400 Bad Request`: Invalid preset ID.
* `403 Forbidden`: Variables feature not enabled for the space.
* `422 Unprocessable Entity`: Attempted removal of variables/presets from active definitions.

**Example response:**

```
{
  "message": "Preset \"German Translation\" must have a value for each variable defined in the workflow definition.",
  "details": {
    "code": "CmaError.Workflows.WorkflowDefinition.PresetMustHaveAllVariables",
    "parameters": {
      "presetName": { "type": "string", "value": "German Translation" }
    }
  }
}
```

## Frontend behavior of Localized workflows

* When users check **"I want to localize this workflow"**, two variables are automatically created: `translator` and `locale`.

* Each **translator–locale pairing** in Localization settings generates a `variableValuePreset`.

* In workflow steps, rules referencing translators automatically link to the `translator` variable, and permissions automatically include the `locale` variable.