---
title: "Request Translation"
method: POST
path: "/connectors-import-api/v3/projects/{projectId}/integrations/{integrationId}/translation-requests"
tags: ["Connectors Import"]
---

# Request Translation

`POST /connectors-import-api/v3/projects/{projectId}/integrations/{integrationId}/translation-requests`

## Request

- Base URL: `https://api.smartling.com`
- URL: `https://api.smartling.com/connectors-import-api/v3/projects/{projectId}/integrations/{integrationId}/translation-requests`
- Auth: HTTP bearer

Submits assets from your connected external system (e.g., Shopify, Intercom, Sanity) for translation in Smartling TMS.
This endpoint orchestrates the content upload process and creates translation requests within a specified job.

## When to Use This Endpoint

Use this endpoint when you need to build a **custom integration** to programmatically request translations outside of the Smartling UI.
This is ideal for:
- Automating translation workflows triggered by events in your system
- Bulk translation requests for multiple assets
- Integrating translation requests into your CI/CD pipeline
- Building custom dashboards or tools that manage translation workflows

**Required Permissions:**
This endpoint is accessible to users with the following roles:
- **Account Owner** - Full administrative access to the account
- **Project Manager** - Manages localization at the project level
- **Requester** - Can submit content for translation

For more information about user roles and permissions, see [Introduction to User Roles](https://help.smartling.com/hc/en-us/articles/360056193134).

**Prerequisites:**
1. You must have a configured connector between Smartling TMS and your external system via the Smartling Dashboard
2. You must have valid asset UIDs and titles from your external system (UID format varies by integration type; title is used as file name prefix in Smartling)
3. You must have a translation job UID where assets will be added
4. You must have target Smartling locale IDs that are both enabled in your project AND configured in the connector's `Language Configuration` (Dashboard → Connector Settings → Language Configuration)

## How It Works

1. **Asynchronous Processing**: This endpoint accepts your request and returns immediately with `translationRequestUids` and `batchUid`
2. **Queue-Based Execution**: Requests are processed via a priority queue. Typical latency is 15-30 seconds, but may take longer under heavy load
3. **Content Fetching**: Smartling pulls source content from your external system using the provided asset UIDs
4. **File Creation**: Each unique asset UID creates one file in Smartling TMS (resubmitting the same asset UID updates the existing file)

## Key Capabilities

- **Batch Submission**: Submit up to 10 assets per request (recommended batch size)
- **Flexible Job Management**: Add assets to new or existing jobs (any status: draft, in-progress, or published)
- **Locale Targeting**: Specify up to 100 target locales with optional workflow assignments per request
- **Authorization Control**: Choose immediate job authorization or keep as draft for manual review

## Important Limitations

- **Job Capacity**: Maximum 5,000 files per translation job
- **Locale Consistency**: All assets in a single request are submitted to the same set of locales
- **Rate Limiting**: Limit calls to 1-2 requests per second to avoid throttling
- **Integration-Specific**: Asset UID format must match your integration type (see `integrationId` parameter)

## Common Anti-Patterns to Avoid

⚠️ DO NOT repeatedly call this endpoint with `authorizeJob: true` for the same job
- Each call triggers job analysis and cost calculation, causing performance degradation
- Instead: Add all assets with `authorizeJob: false`, then authorize once when complete

⚠️ DO NOT submit the same asset multiple times unnecessarily
- Resubmitting updates the existing file but triggers unnecessary processing
- Instead: Track submitted assets and only resubmit when content has changed

⚠️ DO NOT create separate jobs for assets that belong together
- Creates fragmented workflows and complicates project management
- Instead: Batch related assets into the same job (up to 5,000 files)

## Monitoring & Troubleshooting

- **Track Progress**: Use the [Get Batch Status API](#tag/Job-Batches-V2/operation/getJobBatchStatusV2) with the returned `batchUid`
- **Expected Latency**: 15-30 seconds for content to appear in Smartling TMS
- **Error Handling**: 
  - `400` errors are validation failures (not retryable - fix your request)
  - `500/502` errors are transient failures (retryable with exponential backoff)
- **Logging**: Implement monitoring for 5xx errors in production integrations

## Best Practices

- Use small batches (up to 10 assets) for optimal performance and easier error handling
- Reuse traslation job UIDs across multiple API calls to build up job content incrementally
- Set `authorizeJob: false` when adding assets in multiple steps, authorize manually when complete
- Implement exponential backoff retry logic for 5xx errors
- Validate locale IDs against your project configuration before calling the endpoint
- Keep job size under 5,000 files; create new jobs when approaching this limit

## Path parameters

- `projectId` string, required
- `integrationId` 'akeneo' | 'captionhub' | 'contentful' | 'google-drive' | 'intercom' | 'iterable' | 'marketo' | 'sanity-docs' | 'sfcc' | 'shopify' | 'sitecore-xmc' | 'webflow', required

## Request body

- RequestTranslationCommand
  - `assets` Asset[], required: List of assets to be translated. Each asset represents a content item from your external system. **Recommended**: Keep batch size to 10 assets or fewer for optimal performance. **Behavior**: - All assets in this request will be submitted to ALL locales specified in `localeWorkflows` - If you need different locale sets for different assets, make separate API calls - Resubmitting the same `assetUid` updates the existing file in Smartling (does not create duplicates)
    - `assetUid` string, required: Unique identifier for the asset in your external system. This ID must match the format expected by your integration type (see `integrationId` parameter). **Format Requirements**: - Cannot be blank or whitespace-only - Maximum 255 characters - Must be a valid identifier in your external system **Examples by Integration**: - Intercom: `article-12345`, `collection-67890` - Sanity: `page-abc123`, `post-def456` **Behavior**: - Smartling creates one file per unique asset UID - Resubmitting the same UID updates the existing file (no duplicates) - The asset UID is used to fetch source content from your external system
    - `title` string, required: Human-readable title or name of the asset. This title serves two purposes: 1. **File Naming**: Used as a prefix for the file name created in Smartling TMS 2. **Dashboard Display**: Appears in the Smartling Dashboard for identification and organization **Requirements**: - Cannot be blank or whitespace-only - Maximum 500 characters - Should be descriptive enough for translators and project managers to identify the content **Best Practice**: Use the actual content title from your external system for consistency and easier tracking across both systems.
  - `localeWorkflows` ConnectorsImportLocaleWorkflow[], required: Target locales with optional workflow assignments. All assets will be submitted to these locales. **Workflow Assignment**: - If `workflowUid` is `null`, the project's default workflow for that locale is used - Each locale in your Smartling project has a pre-configured default workflow **Validation**: - Locale IDs must be valid Smartling locale codes (e.g., `fr-FR`, not external system codes like `fr`) - Locales must be enabled in your Smartling project - Locales must be configured in the connector's **Language Configuration** (**Dashboard → Connector Settings → Language Configuration**) - Invalid, disabled, or unconfigured locales will return a 400 validation error **Important**: Not all project locales may be available for the connector. Only locales with configured mappings between Smartling and your external system can be used. For example, if your Smartling project has 5 languages but only 3 are configured in Language Configuration, only those 3 can be used with this endpoint.
    - `smartlingLocaleId` string, required: Locale identifier. Either a 2-letter language code (`en`) or a language-region pair (`en-US`). The language part is always lowercase; the region part is always uppercase.
    - `workflowUid` string, nullable: Optional workflow identifier. Must be exactly 12 lowercase alphanumeric characters if provided. **When to specify**: - Use a specific workflow different from the project default - Route content through custom translation workflows **When to omit** (set to `null`): - Use the project's default workflow for this locale - Simplify configuration when defaults are acceptable **Default Behavior**: Each locale in your project has a pre-configured default workflow. If `workflowUid` is `null`, that default is automatically applied.
  - `translationJobUid` string, required: Translation job unique identifier — 12 lowercase alphanumeric characters.
  - `authorizeJob` boolean, required: Controls whether the translation job should be authorized immediately or kept as draft. **When to use `true`** (immediate authorization): - Single API call with all assets ready - Automated workflows where manual review is not needed **When to use `false`** (keep as draft): - Adding assets across multiple API calls - Manual review required before starting translation - Building up job content incrementally **⚠️ Important**: Avoid calling this endpoint multiple times with `authorizeJob: true` for the same job. Each authorization triggers job analysis and cost calculation. Instead, add all assets with `false`, then authorize once manually or via a separate API call.

## Response `200`

Translation request created successfully

- RequestTranslationResponse
  - `response` object
    - `code` 'SUCCESS': Response status code indicating successful request acceptance
    - `data` object
      - `translationRequestUids` string[]: List of unique identifiers for the created translation requests, one per asset. **Note**: These UIDs are for internal tracking. Currently, there is no public API to query individual translation request status using these identifiers.
      - `batchUid` string: Unique identifier for the batch that groups these translation requests. **Monitoring**: Use this UID with the [Get Batch Status API](#tag/Job-Batches-V2/operation/getJobBatchStatusV2) to track processing progress and check for errors. **Typical Flow**: 1. Call this endpoint and receive `batchUid` 2. Wait 15-30 seconds for processing 3. Poll batch status API to verify completion 4. Check Smartling Dashboard to confirm files appear in the job

## Other responses

- `400`: Validation error
- `401`: Provided credentials are not valid.
- `500`: Unexpected error

## Changes

- **2026-10-17** `2cd7a8215799`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/smartling/apis/smartling-rest-api-reference/changes/connectors-import-api/v3/projects/:projectId/integrations/:integrationId/translation-requests/post.md)

---

[API](https://skmtc.dev/smartling/apis/smartling-rest-api-reference.md) - [All operations](https://skmtc.dev/smartling/apis/smartling-rest-api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/smartling/apis/smartling-rest-api-reference/revisions/e63066e7f5e9?raw)