The Acclaro Web Service API is an extensible set of RESTful interfaces that allow customers and partners to automatically manage translation activities with Acclaro, such as file transfers, order creation, quality ratings and status reporting. With the API in use, source content that resides in commercial or custom developed content management systems can be programmatically sent for translation, then subsequently received and published. Any questions or feedback regarding the Acclaro API can be directed to [email protected].
The API throttle limit is 180 requests per minute exceeding which the server will respond with "too many requests" (error code 429).
The Acclaro API uses JSON (javascript object notation) Web Tokens for authentication. To generate valid API tokens, Acclaro customers can follow the steps below:
Each API request must present a valid token. This is placed in the “Authorization” HTTP header with the “Bearer” schema, in a format such as:
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxIiwidmVyIjoiMSJ9.zOrp1SSnBGwlCQMxlEz9rjh-ddThYVuroD9JJmxOgBw
If concern ever arises that a token has been compromised, either through digital theft or through accidental public exposure, tokens may be revoked and uniquely re-generated in the Settings page of the ‘My Acclaro’ customer portal.
The token is an RFC 7519 compliant JSON Web Token containing:
Header
Payload
Signature - HMACSHA256 signature of first two sections
The issue timestamp is used in the revocation list and ensures that every token is unique. The only encryption method supported is HS256. Any attempts to use other encryption methods, such as NONE, will fail.
The Acclaro API is a RESTful interface, residing at:
Arguments to API functions are passed as standard web parameters, which may be URL-encoded if the function is accessed with a GET, for example: https://api.acclaro.com/api/v2/orders?status=new
Arguments may also be encoded into a POST body when using multipart/form-data, usually when a file to be translated is being sent.
Return values are JSON encoded in the HTTP response. Every returned record will contain a field success which will be set to “true” if the call is successful, or “false” if it fails. On failure, there will be two additional fields in the record: errorCode is an integer with values as shown later in this document and errorMessage is a text string explaining the failure. On success, many calls have a field data which points to returned data.
Note that the two calls /orders/{orderid}/quote-document and /orders/{orderid}/files/{fileid} return the file data in the response rather than JSON data. You can differentiate between an error response of JSON data or a successful response of file data by checking the mime type or if the data starts with “{“success":”.
In the My Acclaro portal there is an interactive test console which can be accessed here.
This console enables developers to try out the API functionality and see the output of its calls. It is useful for quick tests of API sample workflows that include creating orders, attaching files and submitting for translation.
Orders can have the following statuses:
Source Files can have the following statuses:
Target Files can have the following status:
An API user may request to receive callbacks when their data changes. Use the call POST /orders/{orderid}/files/{fileid}/callback to be notified when a file changes, or POST /orders/{orderid}/callback to be notified when an order changes. Changes that may trigger a callback include editing an order's attributes, submitting an order, adding a comment to an order, a status change to an order, a finished version of a file appearing, adding a comment to a file, or a file's status changing.
Each of these API calls includes a URL as an argument. Acclaro will perform an HTTP GET operation on the supplied URL when the specified object changes. If your application needs to be passed a particular ID number to properly interpret this callback, please include it in your URL, i.e. https://www.company.com/admin/plugins/acclaro/filecallback.php?oid=12345.
Acclaro batches the dispatch of callbacks, so there may be a delay of several minutes between the object changing and customer notification. For security reasons, we suggest that on receiving a callback, your application should check its database to see that a valid object has been referenced, and then retrieve the current state of that object from Acclaro with GET /orders/{orderid}/files-info or GET order/{orderid}. In this way, invalid or extra callbacks will not cause problems.
Your script which receives the callback should return a successful HTTP response code in the 200 series. If any other response code is returned, we will assume that you failed to process the callback, and repeat it again a few minutes later. If you continue to return unsuccessful responses, we will retry several times before giving up. If you no longer wish to receive callbacks, you may use DELETE /orders/{orderid}/files/{fileid}/callback or DELETE /orders/{orderid}/callback.
The Callback functionality of the Acclaro API enables integration partners to build end to end automated translation workflows that identify and fetch completed translations as soon as they are available. With the power of callbacks, there are also some risks and coding best practices that should be followed to ensure optimal efficiencies for both the sending and receiving systems. For example, any attempts to change orders or files in response to callbacks indicating changes have occurred could create runaway loops. If you have any questions about callbacks or would like any peer review assistance for your integration code, please send your questions and relevant code snippets to [email protected] or contact your Acclaro customer representative.
Similar to callbacks, the API also supports email notifications in a similar fashion with the following calls: POST /orders/{orderid}/files/{fileid}/email, POST /orders/{orderid}/callback, DELETE /orders/{orderid}/files/{fileid}/email and DELETE /orders/{orderid}/email. The same actions that would trigger a web callback will also trigger these emails to be sent.
The email notification messages are intended to be read by a person rather than a program, but do follow a consistent formatting style and contain links to the My Acclaro web portal. These emails are targeted at developers, but can be shared with non-developer colleagues if they would be interested in receiving notifications when relevant order and file statuses change. For more customer-friendly emails, see the delivery options in the My Acclaro portal or use a web callback to invoke a script to send your friendly email.
The due date in the Acclaro API is specified in ISO8601 format. For example, using "2016-09-22" will choose the current time of day on September 22. Using "2016-09-22T11:22" will choose 11:22am on that date, in the default time zone for the portal user account whose web token is being used for authentication. To specify with full time zone consideration, a format such as "2016-09-22T11:22:00-06:00" could be used, which would indicate 6 hours before GMT (United States Central Time).
The Acclaro translation management platform synchronizes its data with the Acclaro API on a frequent basis throughout each day. When leveraging the API’s functions in your application, it may be useful to consider time buffers for ensuring the data reporting accuracy. For example, it may take 15 minutes or more before the status of a newly submitted order displays ‘in progress’. If after an hour the API is reporting status that does not meet expectations, please contact [email protected] to report the issue.
When an API function does not complete normally, the returned record will have success = 0, and errorCode will be set to one of the values below. In addition, errorMessage will have a text string which might be more specific about the problem encountered.
The instructions below define a sample workflow of how a client might leverage the Acclaro API to programmatically submit orders containing source files, check status and download translated deliverables.
If you are building or working with a Content Management System (CMS) and would like to ensure exported source content is optimized for Acclaro to translate and that translated content can be automatically imported back into the CMS, please consider the guidelines below. You may contact us with any questions.
Source content exported from Content Management Systems (CMS) will be processed by Acclaro Localization Engineers for Acclaro Translators to access using industry-standard Computer Assisted Translation (CAT) tools. The aim of the pre-processing is to ensure Acclaro Translators will only be shown content that they are expected to translate, and will not see content that if mistakenly translated could break functionality of the system. After the translators complete their work, post-processing adds in any non-translatable content that was previously stripped, providing clients with the final file formats that they require.
Acclaro’s primary CAT tool as of today is MemoQ by Kilgray, however other tools from other vendors are in use for specific client projects that require unique functionality and translation workflows that MemoQ isn’t the right fit for. The remainder of document describes the general translation file formats that MemoQ and other CAT tools used by Acclaro are able to process and is intended as guidance for CMS translation plugin developers connecting to Acclaro’s Translation Services API.
Various content management systems may support many different data fields on individual pages. In addition to the title and body, additional fields such as metadata, cross-references, slugs etc. Ideally for Acclaro localization engineers to maximize translation efficiencies, all of these fields can be combined into the smallest number of files possible. Situations of having large numbers of files that only have one segment should be avoided if possible.
All files should be encoded: UTF-8.
HTML is natively supported by all CAT tools. Meta tags in HTML header files can be used by CMS plugin exports to enable file id tracking information for status & re-import, as well as information such as source URL, preview URL, target URL, order/job ID , file paths and more.
It is best to avoid placing any of the above metadata in the actual file name, as this tends to make the file names very long and can cause path errors on Windows machines, especially when spaces, special characters and fixed character limitations may result in further complications transferring files & filenames between various content hosting operating systems.
PHP blocks and processing instructions can also be handled by most CAT tools, but whenever possible, translatable content should not be included in these instructions. Poorly formed PHP may not parse correctly, leading to issues with achieving proper page functionality upon import.
XML is supported by all CAT tools. The tools can be configured to include or ignore the content of specific elements and attributes when extracting content for translation. There is no specific set of elements or attributes that is preferred, however a few best practices should be observed:
Acclaro’s translation tools support a wide variety of industry file formats, including HTML, XML, MS Office, and Adobe applications. In most circumstances, it is preferable to receive a single-language file in a common format such as XML or HTML. It is not necessary to use an XLF (or XLIFF) file to transfer content to the Acclaro API but XLF can be supported.
If an XLIFF file is to be used, then the file should be produced using a filtering and segmentation utility that produces standard XLF markup and content organization. This requires that the connector include preparation and post-processing steps to parse content into a segmented bilingual format before export, and reassemble content after import. As a reference, the open-source Okapi Framework can be used to perform pre- and post-processing, as can any number of commercial Translation Management Systems.
It is important to note that simply placing chunks of raw html in CDATA elements within an XLF skeleton will NOT result in a usable XLF file in many cases. The tools that are used to perform the translation in the file will not be able to parse the content correctly, leading to additional effort for engineers and translators, and broken formatting in the final file. Passing content through a filter utility such as Okapi guarantees a well-formed XLIFF with the following features:
If the source content is broken into many small chunks stored in different database fields, it can be useful to use an ‘embedded content’ approach to decrease the number of files created for translation. For example, several small chunks of html or xml that appear on the same page can be placed into a larger XML skeleton using CDATA elements. Below is an example of an XML file that combines the Title and Body fields from the content management database into a single XML file:
{xml}
{head}
{original url=”” id=””}
{preview url=”” id=””}
{target url=”” id=””}
{langs source-language=”” target-language=”}
{/head}
{body}
{content resname=”title”}{![CDATA[page title]]}{/content}
{content resname=”body”}{![CDATA[{h1}This is a heading!{/h1}
{p}this is a paragraph!{/p}]]}{/content}
{/body}
Snippet Notes:
For CMS systems that support a templating language that could allow translatable content to be placed into page templates, as well as database fields, the relationship between template and page may not always be 1-to-1. For example, if Acclaro were asked to translate 100 pages that all use one template, it would not be ideal to embed the template content into every file for every page.
If the source content is distributed across many different resources that don’t have 1-to-1 relationships with a single page, a packaging approach could be leveraged with different file types – for example, XML for content extracted from the database and HTML for templates. A directory structure could then be used which might be built as such:
The package may also include a small number of non-translatable files. For example, a manifest file that contains project metadata and will be used by the CMS when re-importing the files from translation.
Frequently asked questions and answers regarding the Acclaro API are below. For any additional questions, please contact the support team at [email protected]
The Acclaro API uses JSON Web Tokens for authentication. To generate valid API tokens, Acclaro customers can follow the steps below:
Yes, there is a /orders/{orderid}/callback endpoing and a /orders/{orderid}/files/{fileid}/callback which can request that Acclaro invoke a supplied URL when the status of an order changes. Additionally, there are endpoints GET /orders, GET /order/{orderid}, GET /orders/{orderid}/files-info and GET /orders/{orderid}/files/{fileid}/status which provide clients information about their translation status.
The list of supported languages can be accessed with GetLanguages. The Acclaro API supports the 3 letter code language format with 2 letter dialect. The list of supported language pairs can be accessed with GET /info/language-pair .
Yes, the Acclaro API supports XLIFF and is file type agnostic.
Acclaro’s customers’ translations begin based upon existing contractual and service level agreements in place. The current version of the API does not support a quoting workflow, but this is on the near term roadmap for future support.
Yes, the Acclaro API sandbox environment allows partners and clients to safely build and test service integrations and content transfer workflows. Customers and partners can request sandbox access in the same way in which authentication tokens are requested.
Please refer to the ‘Source File Export Guidelines’ included in the Acclaro API Reference Guide for information on how to optimize the formatting of exported source files for Acclaro to translate and then automatically import back into your content database.