Use this article to export content from Smartling as an XLIFF file for translation in an external Computer-Assisted Translation (CAT) tool, then import the completed translations back into Smartling, using the Translation Package API.

This article is for developers building integrations with Smartling. It requires an active Smartling project with API access enabled and a valid API authentication token. 

For full endpoint and parameter details, see the Translation Package API reference.

Translation package overview

A translation package is a snapshot of a project's translatable content for a specific locale and workflow step. 

When you create a translation package through the Translation Package API, Smartling exports the content as an XLIFF file, an industry-standard format supported by most CAT tools.

You can use the Translation Package API for:

• Offline translation: Download content so translators can work in an external CAT tool, then import the completed translations back into Smartling.
• Translation memory export: Export a project's translation memory as a TMX file for use with an external CAT tool.
• Bulk translation import: Import translations completed outside of Smartling or provided by an external source. You can specify whether the imported translations are human-translated or machine-translated (translations generated by an MT engine or LLM provider with no human review).
• Custom workflow automation: Build automated pipelines around Smartling's translation process.

Important considerations before taking translation offline

Taking content out of Smartling for offline translation, whether through the Translation Package API or a manual export, means giving up the safeguards that keep translations fast and accurate inside the platform. Weigh these risks before you build an offline workflow:

• Loss of Visual Context: Translators lose the in-context view available in Smartling, which can make it harder to understand how content will appear in its final context and may result in more mistranslations or QA work.
• Loss of Quality Checks: Your project's Quality Check Profile does not evaluate translations while they are being edited outside of Smartling. As a result, translations can be imported and advanced to the next workflow step even if they contain issues that would normally be flagged by Quality Checks, including high-severity issues.
• Loss of Translation Memory leverage: You can export your translation memory as a TMX file for use in an external CAT tool, but your Smartling leverage configuration and SmartMatch settings do not apply to translation performed outside of Smartling. This can result in losing TM matches and higher translation costs.

• Translation Memory contamination: Imported translations can be saved to your translation memory without the Quality Checks and context available during translation in Smartling. Poor, mismatched, machine-translated, or otherwise unreviewed translations can therefore become available for reuse in future translations.

  By default, translations imported through the Translation Package API are treated as human-translated. If you are importing machine-translated content, set mtContent=true on the import request so Smartling identifies the content as machine-translated rather than human-translated. See Marking translations as machine-translated below.

• Loss of workflow visibility: Once content is exported, Smartling cannot track translation work performed in an external CAT tool. The job's status in Smartling does not reflect progress made outside the platform and does not update until the translated content is imported.
• Markup and code integrity risk: When content is translated in Smartling, underlying code and markup is protected by masking, so translators cannot modify it. In an exported XLIFF file, the code and markup may be visible and can be modified by anyone with access to the file. Changes to code or markup can cause broken functionality and require additional developer time for QA and remediation.

Because these risks apply, it's important to build appropriate safeguards into your integration. For example, validate translated content before importing it and monitor import responses for errors.

Translation Package API vs. manual export

Smartling also supports exporting and importing jobs for offline translation directly from the Jobs Dashboard. This manual workflow does not require development work and may be sufficient if you only need to take a job offline occasionally.

See:

• Export & Import Jobs for Offline Translation (for Account Owners and Project Managers)
• Export and Import Jobs for Offline Translation (for Agency Account Owners and Translation Resource Managers)
• Translating Offline (for Translation Resources)

Use the Translation Package API instead if you need to trigger exports and imports on a schedule, integrate with an external CAT tool's own automation, or build a custom pipeline around a recurring translation process. The considerations above apply either way.

Prerequisites

To use the Translation Package API, you need:

• An active Smartling project with API access enabled.
• A valid API authentication token.
• The workflow step UID for the step you want to export content from. Translation packages are created from a specific workflow step, so you'll need to know your project's workflow configuration. You can find the workflow step UID in the dashboard by navigating to the workflow, clicking on the relevant workflow step, then selecting Manage Step. The workflow step UID is visible in the top right. 
  
  Otherwise you can use the Workflows API to get the workflow step UID.
• Familiarity with the XLIFF format, since completed translations must be re-imported as valid XLIFF files.

End-to-end workflow

Using the Translation Package API follows the same sequence of steps whether you're running a one-time export or automating a recurring pipeline:

1. Create a translation package. Request a package for a locale and workflow step. You can optionally scope it to a specific translation job or a list of string hashcodes. Smartling determines which strings belong to the package right away, and the XLIFF content is available for download as soon as the package exists. By default, Smartling also starts generating a TMX translation memory file in the background; if your integration doesn't need it, set generateTmx to false to skip it.
2. Check whether the TMX is ready (skip if you set generateTmx to false). TMX generation is the only part of package creation that's asynchronous, so check back until it's ready before downloading it. See Package creation time and status polling below for how to poll.
3. Download the XLIFF file. The XLIFF file is always immediately available, generated fresh from the current translation state each time you call this endpoint. It contains the source strings and any existing translations at that workflow step.
4. Download the translation memory (optional). If you generated a TMX file (the default, unless you set generateTmx to false) and it's ready, download it separately. This is useful for seeding an external CAT tool.
5. Download the glossary (optional). If glossaries are configured for the project and locale, the package response also includes a link to download the project's glossary as a TBX file. This is useful for seeding a CAT tool with your account's terminology alongside the translation memory.
6. Translate the content offline. Open the XLIFF file in your external CAT tool and complete the translation work outside of Smartling.
7. Import the completed translations. Upload the translated XLIFF file back into Smartling for the same project and locale. You can optionally have Smartling automatically submit the content to the next workflow step on import. The import is processed synchronously, so the response returns immediately with the total word count and string count imported, along with a list of any strings that failed to import.
8. Check the import status (optional). The import response already tells you how many strings imported successfully. If any strings are listed under import errors, the rest of the import still completed; correct and re-import only the failed strings, rather than the full file. If you need to check the result of a recent import later without having stored the original response, query this endpoint instead.

Marking translations as machine-translated

By default, when you import translations through the Translation Package API, Smartling assumes the content is human-translated. 

If you're importing machine-translated content instead (for example, output from your own MT engine or LLM provider), set the mtContent parameter to true on the import request. 

Setting mtContent=true tells Smartling to treat the imported translations as machine-translated rather than human-translated. This distinction determines how the translations are saved to the translation memory.

Where these machine-translated imports are stored depends on whether your account has Machine Created Translation Memory (MCTM) enabled beyond the default MCTM for AIT translations.

• MCTM is available for AIT (AI Translation) workflows by default, and can also be enabled for MT workflows by special request. This is a special use case that must be specifically enabled for your account. See Machine Created Translation Memory for AIT Translations for more on how the default MCTM works.
• If MCTM is not enabled for your account, translations imported with mtContent=true are not saved to any translation memory. They follow the same rules as machine translation elsewhere in Smartling; see Machine Translation in the Translation Memory for the full set of conditions on when machine translations are saved to translation memory.
• If MCTM is enabled for your account, translations imported with mtContent=true are saved to the MCTM once the string is saved to the translation memory, which happens when the string is published or prepublished. They can also be saved automatically within a few hours through a background process, described below, even if the string is never published. These translation units are labeled MT, rather than human, in the translation memory.
  
  

What is the background process? For accounts where MCTM has been enabled beyond the default AIT use case, Smartling also saves machine translations to the MCTM automatically when they pass through a workflow with human validation steps, even if the string is never published. This happens through a scheduled background process that runs periodically on Smartling's side, typically saving the original machine translation to the MCTM within a few hours, with no action required on your part.

Package creation time and status polling

Creating a translation package determines which strings belong to it right away, and the XLIFF content is generated on demand from the current translation state every time you call the content endpoint, so it's available for download immediately after the package is created. There's nothing to wait for.

The only part of a translation package that's actually asynchronous is the TMX file. By default (generateTmx: true), Smartling generates the TMX in the background after the package is created. The package creation response returns an HTTP 202 if the TMX is still being generated, or an HTTP 200 if you set generateTmx to false, since there's nothing left to wait for.

To check whether the TMX is ready, either:

• Use the dedicated process-tracking endpoint with the processUid from the package's translationMemory link (recommended). It returns detailed status and statistics and is a lighter-weight call than re-requesting the package, or
• Poll the package endpoint and check whether the translationMemory link's processUid has become null.

Either way, Smartling recommends the following polling schedule: wait 2 seconds after the initial request, then check again every 5 seconds, for up to 120 attempts (10 minutes total).

Every API response includes an X-SL-RequestId header. Log this value with each request. If you ever need to contact Smartling support about a package that failed to generate or import, this ID lets support locate the exact request in Smartling's logs.

Importing completed translations, by contrast, is synchronous: Smartling processes the file and returns the results, including word and string counts and any per-string errors, in the same response. There's no waiting or polling required for imports. If you need to check the result of a recent import later without the original response, use the dedicated import status endpoint instead.

Rate limiting

The Translation Package API limits requests to 6 requests per 60 seconds, per user. Exceeding this limit returns an HTTP 429 response.

If you're building an automated integration, especially one processing multiple locales, workflow steps, or jobs, queue your requests rather than firing them in parallel, and add a retry with backoff for any HTTP 429 responses you receive.

Common mistakes to avoid

Keep the following in mind when building around the Translation Package API:

• Only one translation package at a time per locale, workflow step, and job combination. If you request a package that matches one already being generated, Smartling rejects the request until the first one finishes. Before retrying, check the status of the existing package instead of firing off duplicate requests.
• Translation memory exports are on by default. Unless you set generateTmx to false when you create the package, Smartling also generates a TMX file alongside the XLIFF, which adds background processing time. If your integration doesn't need it, set generateTmx to false to skip the extra work; you can't turn TMX generation on or off for a package after it's been created.
• Imports can partially succeed. If some strings in an uploaded XLIFF file fail to import, such as due to a mismatched translation ID or locale, Smartling still imports the strings that are valid. Always check the import response for errors rather than assuming an import either fully succeeded or fully failed, and re-import only the strings that failed.
• Rate limits apply per user. If you're automating requests across multiple locales or jobs, queue them rather than firing them in parallel. See Rate limiting for the exact limits and how to handle HTTP 429 responses.