Smartling APIs

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:

content_org__1_.png

(*) 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 APIIf 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

Authentication 

Base URL:
https://api.smartling.com/auth-api/v2

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



Accounts & Projects API 

Base URL:

https://api.smartling.com/accounts-api/v2/accounts/{accountUid}/projects

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

 

 

Locales

Base URL:https://api.smartling.com/locales-api/v2/dictionary/locales

 

The Locales API allows you to retrieve all available locale codes within Smartling.

 

Files

Base URL:
https://api.smartling.com/files-api/v2

The Files API allows for uploading, downloading, and checking status on files in the Smartling platform.

 

Jobs

Base URL:
https://api.smartling.com/jobs-api/v3

The Jobs API allows for creation, authorization, and modification of translation jobs. 

Context 

Base URL:
https://api.smartling.com/context-api/v2

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.

 

 

Issues

Base URL:
https://api.smartling.com/issues-api/v2

The Issues API allows you to open, manage, and resolve issues related to your source strings and translations. 

Glossaries 

Base URL:
https://api.smartling.com/glossary-api/v2

The Glossaries API allows for managing individual glossary terms and translations, as well as importing and exporting glossary files.

Strings 

Base URL:
https://api.smartling.com/strings-api/v2

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.

Was this article helpful?