Below are key concepts that developers should know when integrating with Smartling.
Account
The top-level customer entity within the Smartling platform. Each Smartling customer gets one account, and all of their translation-related activity takes place within the structure of that account. As a result, your integration will only ever interact with one Smartling account, although it may deal with multiple other items, such as projects.
Project
The entity within which translation work is done in Smartling. Despite the name, projects are long-lived configurations within a Smarting account. They often reflect content types or systems within the customer’s environment. Thus, you might have one Smartling project for your website and a different one for your mobile app. As a result, your integration might be required to interact with multiple Smartling projects. Most translation-related API endpoints include the project ID in the API path.
Source language
The language from which content is being translated. Each project in Smartling has a single source language. Any content sent for translation in a project will be assumed to be in the language defined as the source language for that project.
Target language
The language into which content is being translated. A project is configured with one or more target languages. Requesting translation into a language that’s not configured in a project will result in an error. To see which languages are defined in a project, go to Project Settings > Languages in the Smartling Dashboard, or use the Get project details API call.
Locales and locale codes
A locale is a variant of a language as spoken in a particular location. In Smartling, a locale is written in the form “Language (Location)”. For example, “French (Canada)”. A locale code is a code in the form ab-CD representing a particular locale, where ‘ab’ is the language code and CD is the country code. For example, the locale code for “French (Canada)” is fr-CA. Locale codes are a frequent source of errors in API integrations due to mismatches between what the API client application is using and what is configured in the Smartling project.
Translation memory
A record of previous translations recorded in Smartling as source-target pairs at the string and segment level. Translation memory is automatically surfaced for translators working in the Smartling in the form of suggestions to use in their translation work. It can also be used to apply translations automatically using a capability called SmartMatch. In general, you won’t interact with translation memory in your integration work. However, you can directly influence how effectively translation memory is leveraged by how your content is parsed into strings. As a result, it’s essential to have a solid understanding of how strings are parsed and handled in the platform.
Strings
The basic unit of content in Smartling. Strings are uniquely identified within a Smartling project by the combination of the text of the string, its ‘variant’, and its ‘namespace’. (See Strings.) How strings are parsed from files, and how their variant and namespace attributes are set is based partly on the file type and partly on which directives you specify.
Some key aspects of strings that you should account for carefully in your integration are:
- Placeholders (variables in your text content). Make sure to use placeholders in your content rather than string concatenation which can render your content untranslatable. And make sure that your placeholders are recognized as such by Smartling so that automatic QA checking happens (e.g., ensuring that placeholders in the source string appears in the translation), and translators are prevented from modifying and possibly corrupting your placeholders. Some placeholders are recognized automatically, and some require directives. See Placeholders in Resource Files.
- Keys. If your content has keys, make sure they are being picked up by Smartling and used as variant attributes for your strings. In some cases, this will happen automatically, and in others it will require directives.
- HTML. Smartling automatically recognizes HTML tags and provides tools for translators to ensure that they are protected and handled appropriately. Inline tags such as
<bold>and<a>are retained in the content surfaced to translators, allowing them to position the tags around the appropriate words in the target language. For larger chunks of HTML with block-level tags such as<div>and<li>, it is usually recommended to break them into smaller strings to reduce the chance of translation errors and to get better translation memory leverage. This can be done automatically through the use of a directive.
Directives
Directives are instructions to Smartling indicating how content should be processed. For example, if your content uses a custom placeholder format, you can supply a directive with a regular expression that Smartling can use to recognize placeholders in your content. Directives can be included in files that are uploaded to Smartling, or can be supplied via API parameters. It’s also possible to configure default directives that are always applied when files are uploaded. Available directives for each file type are listed in the documentation for that file type. See Supported File Types.
Files
The primary method of integrating with Smartling for translation is to upload source files and download translated files. In most cases, a translated file is in the same format as the source file, except that the source translatable text is replaced with the corresponding translation. Files are uniquely identified within a project by the file URI, which is also used as the default namespace for the translatable strings from the file. When new versions of previously uploaded files are uploaded, Smartling automatically identifies what's changed (i.e., performs a diff) and only presents the changes for translation.
Job
A grouping of content (strings) to be translated. A job is intended to reflect a real-world body of work sent to translators or a translation agency. As such, in addition to the content, it contains metadata such as due date, attachments, custom attributes, and cost estimates.
A particular string can be in only one job at a time. This can be a source of confusion when a new version of a file is added to a new job, and much of the content doesn’t appear in the job due to its being in another job from an earlier upload.
The API provides a variety of endpoints for managing jobs. In addition, a number of helper APIs (specifically, job batches) are provided to simplify the process of creating jobs.
(Note the term ‘project’ is sometimes used in the translation industry for what is referred to as a 'job' in Smartling.)
Workflow
A customizable sequence of steps through which content moves as part of the translation process. All workflows have a Translation step, and they may have one or more additional Edit, Review, and Hold steps depending on what’s required for the content in question. It’s also possible to configure Dynamic workflows that contain multiple branches through which content is routed based on decision steps. Accounts are usually configured with multiple workflows to be used in different situations.
Content enters a workflow through an action called Authorization. Typically, a job is manually authorized after it has been assessed and its cost estimated; but it’s also possible for it to be authorized via API. Content that is in a job but not yet authorized is said to be Awaiting Authorization.
The last step in a Smartling workflow is called ‘Published’. When all content in a file reaches the Published step for a given locale, it’s ready to be downloaded in that locale. If the appropriate webhook is configured then a callback notification of completion is triggered.
CAT Tool
The primary user interface for translating in Smartling. It provides various tools to help translators produce high-quality translations quickly. Decisions you make in your integration around file formats, placeholders, parsing directives, and visual context can have a significant impact on the experience and effectiveness of translators working in the CAT tool.
Visual Context
A powerful feature of the CAT Tool in which translators see the text being translated in the context where it ultimately is to be displayed. Thus instead of translating a list of isolated sentences, the translator sees the sentences in the web page they’re a part of, and sees how the layout of the page accommodates the translations. Visual context results in higher-quality translations in a shorter time with simpler review workflows. Smartling provides a number of tools for capturing and loading context into the platform, including a set of API endpoints.