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.

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 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

{
  "assets": [
    {
      "assetUid": "article-12345",
      "title": "Getting Started Guide"
    }
  ],
  "localeWorkflows": [
    {
      "smartlingLocaleId": "fr-FR",
      "workflowUid": "wf1234567890"
    }
  ],
  "translationJobUid": "j45v1uvsi3tx",
  "authorizeJob": true
}

{
  "response": {
    "data": {
      "translationRequestUids": [
        "req123abc456",
        "req789def012"
      ],
      "batchUid": "batch12345678"
    }
  }
}