Smartling’s Translation Delivery (TD) API is a high-availability, non-blocking API that enables easy content ingestion and translation retrieval. It offers low-latency, high-throughput performance for fetching localized content to be served on websites and mobile apps. Unlike Smartling’s GDN proxy service, which connects to a source server (i.e., proxying a request), this API processes source content in your request and immediately responds with available translations for that content, making it a helpful tool for both ingesting content and retrieving translations on demand. The API can be used as a standalone solution or in conjunction with the GDN proxy.
Please note that this API is a paid product. For pricing information, please reach out to your Smartling Customer Success Manager.
How it works
The TD API is similar to Smartling’s GDN proxy—it provides an alternative method for ingesting content and retrieving translations for use in your website or app. The key difference is that, instead of behaving as a proxy, it works as an API endpoint.
To compare:
The GDN proxy receives a content request from a browser visiting a localized site and then makes the same request to the source site. It receives that content in a response from the source site, which it then passes back to the browser with translations substituted in place of the source content.
The TD API does not power localized websites directly. Instead, it processes requests from other systems that are configured to push and pull data. Unlike the GDN proxy, which is triggered by a page visit to a localized domain, the TD API receives a request that includes a payload already containing the source content for translation. This content is quickly ingested, and the API immediately responds with any available translations for the source content.
In this way, Smartling acts as a translation database–storing translations and delivering them upon request. Once translations are published in Smartling, repeating the same request will return the finalized translations, ready to be used wherever needed in your application or site.
How is it different from the Files or Strings API?
Other content ingestion APIs, such as Files and Strings work asynchronously. In other words, they are not designed for high-throughput access and are better suited for processes that do not require immediate responses. These APIs have different endpoints for uploading source content and downloading translations. The TD API is a single endpoint that receives content and immediately responds with any available translations.
The default behavior of the TD API is to store only one copy of a string, regardless of where it is used. This means that if the same string is contained in multiple payloads sent for translation, the system will ingest only one copy and re-use the same string and translation for all those payloads. This provides flexibility when managing source content because there is no dependency between the container (file, payload, URL, etc.) and the translation. If the source string has been ingested before, it will be included in the response, regardless of what other content is in the current API post.
Translation process for the TD API
All content ingested into the Smartling platform must be put into a job and run through a workflow that uses your preferred translation types. Content ingested from the TD API is not treated differently and will pass through the same steps.
Once translations are completed they will instantly be available and the next time any of those strings are posted to the TD API, the response will contain those completed translations.
Use cases
The TD API is a flexible solution that supports a wide range of use cases. Here are a few examples of how it can be used:
- Strict security or performance requirements: For customers with strict security policies or performance constraints, the API enables content ingestion and delivery without using the GDN proxy.
-
Bulk translation retrieval: If content has already been ingested through the GDN, the API can be used to fetch large sets of translations in bulk. Examples might include a data feed from a marketing platform that reuses translations for content already deployed in other parts of your tech stack.
- Real-time delivery for apps: Ideal for mobile apps or web applications that need to serve translated content instantly, without the need for a build or deployment process. Some customers use the TD API to generate an updated translation package that is deployed to a CDN. From there, mobile apps or web apps can read the updated translations and seamlessly receive those updates on-the-fly.
Getting started
If you’re interested in using the TD API, please contact your Customer Success Manager or Solution Architect to determine whether this solution is the best fit for your use case.
Although the TD API does not need to be used with the GDN translation proxy, the two can be used together. In order to work with the TD API, you must create a GDN project. This project provides the infrastructure and settings required to use the TD API. Creating a GDN project does not mean you will be using, or need to use, the GDN proxy.
Once your GDN project is created, a special GDN rule must be added to enable use of the TD API. You will also need a domain for ingesting content. If you already have an existing GDN project, you can use your localized domain to ingest content into Smartling. If not, your Solution Architect can help set up a temporary domain for use with the TD API.
Request structure
The TD API supports the following content types: HTML, JSON, XML, JavaScript, or mixed types (e.g., JSON+HTML, XML+HTML).
Below is an example curl request of a JSON payload to ingest/translate:
curl -v 'http://fr-ca-0d553a54910123456.getsmartling.com/sl-api/example/path/' \
-H 'Content-Type: application/json;charset=UTF-8' \
--data-raw '{"sl_translate":"sl_all","key":"Change password"}' \ --compressed
Key elements:
-
Domain: This is your localized domain from the Smartling GDN project. For example:
http://fr-ca-0d553a54910123456.getsmartling.com -
URL Path: The path must begin with
/sl-api/. The remainder of the path can be anything you choose, and determines the URL to which the string will be associated in Smartling.
Example:/sl-api/example/path/ -
Parsing Directive: In the example above,
"sl_translate":"sl_all"tells Smartling to ingest all key values for translation. In this case, the text to be translated is “Change password.” The directive(s), or GDN tags, you use depends on the type of content being sent and what content you want to translate. If you are sending entire files, you can also include directives directly within the file to control how the content is parsed. Additionally, parsing behavior can be controlled via rules.
Response structure
If a published (or pre-published) translation exists for the string, the translation will be returned in the response. If no translation exists in Smartling, the response returns the source text.
Example:
{"sl_translate":"sl_all","key":"Changer le mot de passe"}
GDN features supported by the TD API
The TD API supports many of the same features as the GDN proxy, including:
- Namespaces: Used when you want to translate the same string differently across various pages or HTML elements.
- Variants: Allow you to distinguish between two unique strings that share the same source text.
- Placeholders: Represent dynamic variable content. These are words or tokens within a string that should not be translated but must appear in the translation.
- Rules and rewrites: Provide granular control over content ingestion, parsing behavior, and how translated content is displayed.
- Content swaps: Enable you to replace a section of content on a specific translated page or site.
- Visual context: Offers translators and editors a visual representation of the source content in the Smartling CAT Tool. Visual context is generated automatically, but you can also provide it manually or through an external tool.
- Security: Includes support for IP restrictions, authentication, and other security measures.