Overview of Smartling APIs
This article is for anyone who wants to use the Smartling APIs.
Content Organization
Content in Smartling is generally organized and prioritized in the following hierarchy:
(*) Translation memories can be shared across multiple projects.
Account
Each Smartling customer is provisioned with their own Smartling account, identified by an accountUid. Within your account, you can have any number of projects, identified by a projectUid.
Smartling APIs are going to have embedded in the URL, an accountUid or a projectUid. If you're just getting started, you can retrieve your accountUid and projectUid by logging into dashboard.smartling.com > API.
Projects
Smartling projects are translation environments that are used to segment or bucket your various content types, such as websites, web applications, mobile, support documentation, etc. These projects contain a collection of settings that change infrequently, such as available languages, linguistic packages, etc. Projects are a great way of organizing the different content that you'll be adding to Smartling.
Within a project, any number of locales can be configured. Locales are the available languages into which you can translate. For example, if you have "fr-FR" configured for your project, this enables you to translate into French (France).
- To know which locales are available for a given project, you can use the Project Details API. If you're unsure which locales you're going to need, you can always change them at a later date.
- The full list of locales can be retrieved by using the Locales API.
Locales
Within a project, any number of locales can be configured. Locales are the available locales you can translate into. For example, if you have fr-FR configured for your project, then this will enable you to translate into French (France). If you ever want to know which locales are available for a given project, you can use the Project Details API. If you’re unsure which locales you’re going to need, no worries, you can always change them later. The full list of locales available are listed here.
Jobs
Each project may contain one or more jobs. Jobs allow you to group and prioritize content for translation by due date, as well as monitor progress throughout completion. They are crucial to your API workflow and are the most effective way to communicate priority with your linguists, as content flows across your account.
Files
Smartling customers typically choose to use files when adding their content to Smartling.
Smartling supports a wide variety of file types. When you upload a file to Smartling, Smartling will break down the file into strings that will be sent for translation.
Strings
Each job contains strings (words or phrases) that will be translated. Smartling extracts strings from the captured content based on the paragraph markers found in your content. Those markers vary depending on the content or file type. For example, for HTML, everything in a <div> tag may be considered one string.
Want to view a sample of a typical API workflow? See our API Flow Diagram.
Using Smartling APIs
Smartling APIs enable you to automate many of the actions that users ordinarily perform in Smartling's web-based application. It also allows you to build integrations to connect your content sources directly with Smartling.
Translation is typically performed by human Translators. The API is used to automate the process of uploading your content, packaging your content into Jobs, and downloading your translated content. This increases efficiency and lets business users focus on monitoring progress, address any questions from Translators and review translations once completed, rather than focusing on getting content in and out of Smartling.
List of APIs
| API and Base URL | Description |
|
Base URL: |
Smartling APIs use OAuth 2.0 authentication. The Authentication API provides the access token to authenticate API calls. The access token needs to be in the header of every request: -H “Authorization: Bearer {accesstoken}"
|
|
Base URL:
|
The Accounts & Projects API allows you to manage your account and projects. (A project is your workspace for your translation content, and lives within your account.)
|
|
Base URL:
|
The Locales API allows you to retrieve all available locale codes within Smartling.
|
|
Base URL: |
The Files API allows for uploading, downloading, and checking status on files in the Smartling platform.
|
|
Base URL: |
The Jobs API allows for creation, authorization, and modification of translation jobs. |
|
Base URL: |
The Context API supports uploading various forms of context (images and HTML), and associate the context with content in Smartling. This provides a full graphical context for your content.
|
|
Base URL: |
The Issues API allows you to open, manage, and resolve issues related to your source strings and translations. |
|
Base URL: |
The Glossaries API allows for managing individual glossary terms and translations, as well as importing and exporting glossary files. |
|
Base URL: |
The Strings API allows for creating individual strings not associated with files, and downloading translated strings.
|
Response Format
Success responses are encoded into a generalized JSON structure with two basic properties: a response code, and a custom data object.
A success response is returned as either a 200 or a 202. All success responses will be in the following format:
{
"response": {
"code": "SUCCESS",
"data": {
}
}
}
The data object returned is dependent on the particular API being called.
| Value | Description | HTTP Code |
| SUCCESS | If the service request was processed normally. | 200 |
| ACCEPTED | If an asynchronous task has begun, such as a file upload, but hasn't completed at the time the response is sent. | 202 |
| VALIDATION_ERROR | If something specific was wrong with the request parameters provided. One or more will describe the particular invalid parameter. | 400 |
| AUTHENTICATION_ERROR | If the provided credentials were not valid. | 401 |
| AUTHORIZATION_ERROR | Legacy error code from API. | 401 |
| RESOURCE_LOCKED | The requested file is currently being processed by another operation. The file will be unlocked after the operation completes. | 423 |
| MAX_OPERATIONS_LIMIT_EXCEEDED | Too many simultaneous API requests per project or file. | 429 |
| GENERAL_ERROR | If an unexpected error occurred during the service request processing. | 500 |
| MAINTENANCE_MODE_ERROR | If Smartling has entered maintenance mode, all API services will return this error. After exiting maintenance mode, all services should return to normal. | 503 |
Rate Limits
When using our APIs, Smartling imposes rate limits on requests to ensure that resources are shared fairly among clients. If you make a high number of requests in a short time period, some requests may fail.
If rate limiting is applied, a 429 MAX_OPERATIONS_LIMIT_EXCEEDED response will be sent. Your integration should be setup to wait and retry a request if a 429 response is received.
Where possible, spread out your requests to avoid running into rate-limiting issues.
Tracking and Debugging Requests
Smartling adds a reference header to each API response so that customers can track request/responses. This is useful if debugging is needed with the help of Smartling. For example, the header may appear as:
X-SL-RequestId:mdj38so9-472c-4bf8-9606-91233568e997
SDKs and CLI
Smartling also has tools to help facilitate using our APIs, such as our SDKs and CLI tool.