HTML Context API

The HTML context API allows you to submit HTML for the purpose of providing context for your source content that will be shown in the Smartling Translation Interface. Smartling analyzes the HTML content you upload for context and matches strings in a Smartling project. When Smartling finds a match, the HTML you provided becomes the visual context that users see in the Smartling Translation Interface. Smartling will not create any new content from the HTML uploaded to the context matching service, and every unique string in Smartling can have only one context.

Smartling persistently stores the HTML you provide to this service. In order for context to look correct when it is used in the Smartling Translation Interface, the service attempts to “inline” static resources (CSS, JavaScript, images) if any are externally referenced from the HTML page you submitted. These resources need to be publicly available in order for Smartling to access them. If this is not possible, consider using the automation features of the Smartling Context Capture Extension for Chrome to capture context.

Smartling organizes content by URLs and URL context groups, and Files. The service will not change the context for strings that are already contextualized unless you specifically use the override directive. This is functionally equivalent to using the Chrome Plugin and overwriting context by selecting specific strings. Context groups are created automatically when you add context and use a URL that already has strings associated with it. Creating a new context group will not change strings that already have context with that URL. Strings that have no context before the call will appear in a separate group under the same URL.

All API URLs have the following base: https://api.smartling.com/v1, and all of the following calls require both the apiKey andprojectId parameter which you can find within your Smartling project's dashboard: https://dashboard.smartling.com/settings/api

Smartling supports string variants, which are duplications of the same string with different keys for context. You cannot specify which variant of a string you are contextualizing with the current version of this API.

HTMLContextUpload (/v1/context/html?action=upload)

Uploads an HTML payload to be analyzed for use as context for strings in the same project.


Parameters

apiKey (required)

The API Key for your account. Available in the Smartling dashboard at Project Settings>API.

projectId (required)

The unique ID for your project. Available in the Smartling dashboard at Project Settings>API.

action (required)

The only allowed value is upload

html (required)

The HTML formatted content that includes strings you want to contextualize. The HTML can be a fragment, inlined HTML, or the HTML as it appears on your site. If there are any external resources referenced, Smartling inlines them.

url (required)

The URL that Smartling displays in the dashboard if any content is matched. This URL may already exist in your Smartling project. If providing context for content for a website, using the corresponding site URL is recommended. If you reuse a URL, strings will be grouped by individual contexts, that is you can send separate HTML payloads and re-use the same URL, Smartling will create multiple context groups for that single URL.

fileUri (optional)

Unique identifier for a file in a Smartling project. If specified, the content uploaded will be matched only against strings in the specified file, instead of all strings in the project.

Returns
{
"requestID" : "[number]"
}

requestID

The unique request ID created for each request. Use this ID with the getStats service to obtain statistics on the request. You must save this ID if you want to call getStats, there is no service to list all your uploads.

Examples

HTMLContextStats (/v1/context/html?action=getStats)

Provides status and statistics on a specific request.


Parameters

apiKey (required)

The API Key for your account. Available in the Smartling dashboard at Project Settings>API.

projectId (required)

The unique ID for your project. Available in the Smartling dashboard at Project Settings>API.

action (required)

The only allowed value is getStats

requestID (required)

The request ID number returned from a successful upload.

Returns
{
"status" : "[PROCESSED]",
"checkedStringsCount" : "[number]",
"matchedStringsCount" : "[number]",
"updatedStringsCount" : "[number]"
}

status

Status of the contextualization request. Possible values returned include: NOT_FOUND, INITIATED, PROCESSING, PROCESSED, FAILED

checkedStringsCount

The number of strings that were checked during the analysis.

matchedStringsCount

The number of strings that were matched.

updatedStringsCount

The number of strings where Smartling updated context resulting from a match.

This is not always equal to the matchedStringsCount. If a string already has context then it will not be updated unless the override class has been set (see Special HTML classes below). Also, if the same string is found multiple times then only the first occurrence of the string is updated for context.

Examples

Special HTML Classes

To control the matching process, you can use several HTML classes (sample file).

Class Name Description
sl-notranslate Smartling will not match text inside an sl-notranslate block, including all nested tags. You can use nested sl-translate blocks to override the behavior of sl-notranslate. Note that this is different from the behavior of no-translate directives for the Global Delivery Network.
sl-translate Should be used to override behavior of sl-notranslate class for nested text blocks
sl-override-context

By default, Smartling will not override existing context for a string, even if it finds the string more than once. You can use the sl-override-context class to change this behavior. Smartling will update context for a string inside sl-override-context on every submission.

You can also use the clear context feature in the dashboard to remove a string's context, and then recontexualize it using the API or the Smartling Context Capture Extension for Chrome.