---
title: "Apply Auto-Translation"
method: POST
path: "/projects/{projectId}/pre-translations"
tags: ["Translations"]
---

# Apply Auto-Translation

`POST /projects/{projectId}/pre-translations`

## Request

- Base URL: `https://api.crowdin.com/api/v2`
- URL: `https://api.crowdin.com/api/v2/projects/{projectId}/pre-translations`
- Auth: none declared
- TypeScript: <https://skmtc.dev/crowdin/apis/crowdin-api-v2/docs/projects/:projectId/pre-translations/post.ts> (a function with typed inputs; its response is checked against the schema)

**Required scopes:** `project.translation` (Read and Write).

## Path parameters

- `projectId` integer, required

## Request body

- union
  - object
    - `languageIds` string[], required: Set of languages to which auto-translation should be applied. Get via [List Supported Languages](#operation/api.languages.getMany)
    - `branchIds` integer[]: Branches array that should be translated
    - `translateUntranslatedOnly` boolean: **Deprecated.** Use the `scope` parameter instead: - pass `scope: "untranslated"` to apply auto-translation to untranslated strings only (equivalent to the legacy `true`), - pass `scope: "all"` to apply auto-translation to both untranslated and translated strings (equivalent to the legacy `false`). Kept for backward compatibility with existing API integrations. Cannot be used together with `scope` in the same request.
    - `labelIds` integer[]: Label Identifiers. Get via [List Labels](#operation/api.projects.labels.getMany)
    - `excludeLabelIds` integer[]: Label Identifiers. Get via [List Labels](#operation/api.projects.labels.getMany)
    - `labelMatchRule` 'all' | 'any': How a string is matched against `labelIds`. One of: `all` — the string carries every one of the labels, `any` — at least one of them. Default is `all` __Note:__ Must be used together with `labelIds`
    - `excludeLabelMatchRule` 'all' | 'any': How a string is matched against `excludeLabelIds`. One of: `all` — only a string carrying every one of the labels is skipped, `any` — a string carrying at least one of them is skipped. Default is `all` __Note:__ Must be used together with `excludeLabelIds`
    - `method` 'tm' | 'mt' | 'ai': Defines auto-translation method. Available values: - 'tm' – auto-translation via Translation Memory - 'mt' – auto-translation via Machine Translation. 'mt' should be used with `engineId` parameter - 'ai' – auto-translation via AI. 'ai' should be used with `aiPromptId` parameter
    - `priority` 'low' | 'normal' | 'high'
    - `engineId` integer: Machine Translation engine Identifier. Read more about how to get the [MT engine identifier](https://support.crowdin.com/configuring-machine-translation-engines#mt-engine-ids).
    - `aiPromptId` integer: AI Prompt Identifier. Get via [List AI Prompts](#operation/api.ai.prompts.getMany)
    - `autoApproveOption` 'all' | 'exceptAutoSubstituted' | 'perfectMatchApprovedOnly' | 'perfectMatchOnly' | 'none': Defines which translations added by TM auto-translation should be auto-approved. Available values: - 'all' – all - 'perfectMatchOnly' – with perfect TM match - 'exceptAutoSubstituted' – all (skip auto-substituted suggestions) - 'perfectMatchApprovedOnly' - with perfect TM match (approved previously) - 'none' – no auto-approve
    - `duplicateTranslations` boolean: Adds translations even if the same translation already exists. Default is `false`. __Note:__ Cannot be used when `replaceTranslationsOption` is `all` (replacing all translations already overrides duplicate handling).
    - `skipApprovedTranslations` boolean: Skip strings that already have approved translations. Default is `false`. __Note:__ Cannot be used together with `resetApprovalStatus`.
    - `scope` 'untranslated' | 'translated' | 'all': Which strings to apply auto-translation to. Default is `untranslated`. Available values: - 'untranslated' – strings without an existing translation (default) - 'translated' – strings that already have a translation (re-translation) - 'all' – both untranslated and translated strings __Note:__ Cannot be used together with the deprecated `translateUntranslatedOnly`.
    - `translationModifiedBefore` string, date-time, nullable: Re-translates only if a string's current translation was modified prior to this date. Useful after modifying contextual resources like screenshots, style guides, or glossaries. __Note:__ Requires `scope` to be `translated` or `all`. Cannot be used with `scope: "untranslated"` or `translateUntranslatedOnly: true`.
    - `translationModifiedAfter` string, date-time, nullable: Re-translates only if a string's current translation was modified after this date. Can be combined with `translationModifiedBefore` to define a date range. __Note:__ Cannot be later than `translationModifiedBefore`. Requires `scope` to be `translated` or `all`. Cannot be used with `scope: "untranslated"` or `translateUntranslatedOnly: true`.
    - `replaceTranslationsOption` 'none' | 'autoTranslated' | 'all': Defines whether to replace existing translations with new auto-translations. Default is `none`. Available values: - 'none' – add the new translation alongside existing ones (default) - 'autoTranslated' – replace auto-generated translations (TM, MT, AI). Human translations are kept - 'all' – replace all existing translations __Note:__ Values other than `none` require `scope` to be `translated` or `all` (cannot be combined with `scope: "untranslated"` or `translateUntranslatedOnly: true`).
    - `resetApprovalStatus` boolean: Removes approval on existing translations when applying auto-translations. Default is `false`. __Note:__ Requires `scope` to be `translated` or `all`. Cannot be used together with `skipApprovedTranslations`, `autoApproveOption` (any value other than `none`), or when `replaceTranslationsOption` is `all` (replaced translations lose approval automatically). Cannot be used with `scope: "untranslated"` or `translateUntranslatedOnly: true`.
    - `notifyOnCompletion` boolean: If `true`, the user who started the Auto-Translation is notified when it finishes, fails or is canceled. __Note:__ The notification is sent only via the channels the user enabled for the Auto-Translation notification group
    - `translateWithPerfectMatchOnly` boolean: Applies auto-translation only for the strings with perfect match (source text and contextual information are identical) __Note:__ Works only with TM auto-translation method
    - `fallbackLanguages` FallbackLanguagesScheme: Defines fallback languages mapping. The passed value should be an associative array containing both language id and array of fallback language ids: - `{languageId}` – Crowdin id for the specified language. Get via [List Supported Languages](#operation/api.languages.getMany) - `Array of strings` – an array containing fallback language ids. Get via [List Supported Languages](#operation/api.languages.getMany) __Note:__ Available only for TM Auto-Translation
      - `languageId` string[]
    - `sourceLanguageId` string: Source language identifier. Get via [Project Target Languages](#operation/api.projects.get)
    - `customInstruction` string: Custom instruction for AI auto-translation. This instruction will be appended to the AI prompt text. __Note:__ Available only for AI auto-translation method
  - object: Applies auto-translation to the strings of the specified task. The target language is taken from the task
    - `taskId` integer, required: Task Identifier. Get via [List Tasks](#operation/api.projects.tasks.getMany)
    - `method` 'tm' | 'mt' | 'ai': Defines auto-translation method. Available values: - 'tm' – auto-translation via Translation Memory - 'mt' – auto-translation via Machine Translation. 'mt' should be used with `engineId` parameter - 'ai' – auto-translation via AI. 'ai' should be used with `aiPromptId` parameter
    - `priority` 'low' | 'normal' | 'high'
    - `engineId` integer: Machine Translation engine Identifier. Read more about how to get the [MT engine identifier](https://support.crowdin.com/configuring-machine-translation-engines#mt-engine-ids).
    - `aiPromptId` integer: AI Prompt Identifier. Get via [List AI Prompts](#operation/api.ai.prompts.getMany)
    - `autoApproveOption` 'all' | 'exceptAutoSubstituted' | 'perfectMatchApprovedOnly' | 'perfectMatchOnly' | 'none': Defines which translations added by TM auto-translation should be auto-approved. Available values: - 'all' – all - 'perfectMatchOnly' – with perfect TM match - 'exceptAutoSubstituted' – all (skip auto-substituted suggestions) - 'perfectMatchApprovedOnly' - with perfect TM match (approved previously) - 'none' – no auto-approve
    - `duplicateTranslations` boolean: Adds translations even if the same translation already exists. Default is `false`. __Note:__ Cannot be used when `replaceTranslationsOption` is `all` (replacing all translations already overrides duplicate handling).
    - `skipApprovedTranslations` boolean: Skip strings that already have approved translations. Default is `false`. __Note:__ Cannot be used together with `resetApprovalStatus`.
    - `scope` 'untranslated' | 'translated' | 'all': Which strings to apply auto-translation to. Default is `untranslated`. Available values: - 'untranslated' – strings without an existing translation (default) - 'translated' – strings that already have a translation (re-translation) - 'all' – both untranslated and translated strings __Note:__ Cannot be used together with the deprecated `translateUntranslatedOnly`.
    - `translationModifiedBefore` string, date-time, nullable: Re-translates only if a string's current translation was modified prior to this date. Useful after modifying contextual resources like screenshots, style guides, or glossaries. __Note:__ Requires `scope` to be `translated` or `all`. Cannot be used with `scope: "untranslated"` or `translateUntranslatedOnly: true`.
    - `translationModifiedAfter` string, date-time, nullable: Re-translates only if a string's current translation was modified after this date. Can be combined with `translationModifiedBefore` to define a date range. __Note:__ Cannot be later than `translationModifiedBefore`. Requires `scope` to be `translated` or `all`. Cannot be used with `scope: "untranslated"` or `translateUntranslatedOnly: true`.
    - `replaceTranslationsOption` 'none' | 'autoTranslated' | 'all': Defines whether to replace existing translations with new auto-translations. Default is `none`. Available values: - 'none' – add the new translation alongside existing ones (default) - 'autoTranslated' – replace auto-generated translations (TM, MT, AI). Human translations are kept - 'all' – replace all existing translations __Note:__ Values other than `none` require `scope` to be `translated` or `all` (cannot be combined with `scope: "untranslated"` or `translateUntranslatedOnly: true`).
    - `resetApprovalStatus` boolean: Removes approval on existing translations when applying auto-translations. Default is `false`. __Note:__ Requires `scope` to be `translated` or `all`. Cannot be used together with `skipApprovedTranslations`, `autoApproveOption` (any value other than `none`), or when `replaceTranslationsOption` is `all` (replaced translations lose approval automatically). Cannot be used with `scope: "untranslated"` or `translateUntranslatedOnly: true`.
    - `notifyOnCompletion` boolean: If `true`, the user who started the Auto-Translation is notified when it finishes, fails or is canceled. __Note:__ The notification is sent only via the channels the user enabled for the Auto-Translation notification group
    - `translateWithPerfectMatchOnly` boolean: Applies auto-translation only for the strings with perfect match (source text and contextual information are identical) __Note:__ Works only with TM auto-translation method
    - `fallbackLanguages` FallbackLanguagesScheme: Defines fallback languages mapping. The passed value should be an associative array containing both language id and array of fallback language ids: - `{languageId}` – Crowdin id for the specified language. Get via [List Supported Languages](#operation/api.languages.getMany) - `Array of strings` – an array containing fallback language ids. Get via [List Supported Languages](#operation/api.languages.getMany) __Note:__ Available only for TM Auto-Translation
      - `languageId` string[]
    - `sourceLanguageId` string: Source language identifier. Get via [Project Target Languages](#operation/api.projects.get)
    - `customInstruction` string: Custom instruction for AI auto-translation. This instruction will be appended to the AI prompt text. __Note:__ Available only for AI auto-translation method

## Response `202`

Auto-translation was successfully started

- CrowdinPreTranslationResource: Base schema of resource container. Container is a wrapper object that contains payload in required `data` property and provides space for adding any other metadata.
  - `data` CrowdinPreTranslation, required
    - `identifier` string
    - `status` 'created' | 'in_progress' | 'canceled' | 'failed' | 'finished'
    - `progress` integer: in percentages
    - `attributes` CrowdinPreTranslateAttributes
      - `languageIds` string[]
      - `branchIds` integer[]
      - `taskId` integer: ID of the task the auto-translation was applied to. Present only when the auto-translation was requested by `taskId`
      - `method` string
      - `autoApproveOption` string
      - `duplicateTranslations` boolean
      - `skipApprovedTranslations` boolean
      - `translateUntranslatedOnly` boolean: **Deprecated.** Reflects the legacy value sent in the request (defaults to `true` when not provided). New integrations should rely on `scope` instead.
      - `scope` 'untranslated' | 'translated' | 'all'
      - `translationModifiedBefore` string, date-time, nullable
      - `translationModifiedAfter` string, date-time, nullable
      - `replaceTranslationsOption` 'none' | 'autoTranslated' | 'all'
      - `resetApprovalStatus` boolean
      - `translateWithPerfectMatchOnly` boolean
      - `priority` 'low' | 'normal' | 'high'
      - `notifyOnCompletion` boolean
    - `createdAt` string, date-time
    - `updatedAt` string, date-time
    - `startedAt` string, date-time
    - `finishedAt` string, date-time

## Other responses

- `400`: Invalid Request Parameters
- `401`: Unauthorized
- `402`: Payment required
- `403`: Forbidden
- `404`: Project with specified id was not found
- `405`: Method Not Allowed
- `422`: Unprocessable Entity
- `503`: Service Unavailable

---

[API](https://skmtc.dev/crowdin/apis/crowdin-api-v2.md) - [All operations](https://skmtc.dev/crowdin/apis/crowdin-api-v2/llms.txt) - [OpenAPI document](https://skmtc.dev/crowdin/apis/crowdin-api-v2/revisions/27aae7751699?raw)