Introduction to Integrating Smartling

Smartling's Hosted Connector Configuration Overview

The article is a general overview of Smartling Hosted Connector configurations, to clarify some concepts you may want to consider and discuss with your Customer Success Manager and Solutions Architect. Key concepts explored include;

Here's the full list of Smartling's Hosted Connectors for which this article is relevant;

Some specific concepts in this article may be relevant to some, but not all of these Connectors. For additional detailed information about specific Connectors, please visit our multiple articles on each Connector.

Connecting platform refers to the external platform you are integrating with Smartling using a Smartling Hosted Connector, for example, Yext, Episerver, or Zendesk.

Set up a Connector Project in Smartling

If you decide to integrate an application via one of our Connectors, the first thing you need to do is set up a Connector Project in Smartling. Read about how to create a Project here.

Oauth / Connection Settings

Once you have set up your Connector Project in Smartling, the first step in connecting Smartling to your connecting platform is inserting the connecting platform's credentials into Smartling. This can be done in a variety of ways, depending on the connection. You may need to insert API Keys, Tokens, and a password, or you may need to connect using an OAuth.

OAuth (Open Authorization) is an open standard authorization framework for token-based authorization and it provides the ability to connect your Smartling account to another application securely, without sharing visibility over credentials. In any case, the method will be fully secure and tokenized.

Language Configuration

You will have already configured your source and target locales in Smartling, and also in your connecting platform. The Language Configuration section of the Connector Settings is to ensure that each of the language pairs is mapped correctly between each application.

Source Locale Mapping

The Smartling source language should match the Connector source language. Some Connector configurations will already be correctly configured for source locale mapping. Your connecting platform will typically have native localization support. This means it provides Smartling with a list of supported locales, so you can choose from these locales in the Source Locale dropdown list in your Connector Configuration within Smartling.

Target Locale Mapping

It is important to ensure that each of the target locales is mapped correctly. Some Connector configurations will display the Smartling target locale chosen from within Smartling, and an empty field to input the appropriate target locale from within the connecting platform. Ensure the target locale matches exactly to what it is identified as in the Connector. For example, if your Smartling target language is German (Germany), check your connecting platform to find out its equivalent, eg: de or de-DE or German.

General

General Connector configurations include changed content behavior settings and the frequency in which Smartling checks for content changes. Here, you can configure the behavior of the connector when your source content changes.

Automation of Prior Requests for Translation

Configuration: How do you want Smartling to handle changes to the source content for items that you have previously requested to be translated?

Dropdown menu options:

  • Auto: The Smartling Connector will detect changes to your source content every 3 hours. Any changes detected to the source content will be submitted to Smartling for translation, batched into a job and sit in awaiting authorization. Smartling will not detect net new content, only updates to content that have been submitted for translation in the past.
  • Manual: The Smartling Connector will detect changes to source content every 3 hours, and will not submit new content for translation. Enabling this setting will activate the “Outdated” column in your connector’s Progress page, or you will see a Show Outdated tick box under the Progress filters.
  • Disabled: The Smartling Connector will not check for source content changes.

Changed Content Behavior Frequency 

Configuration: Polling Schedule - How frequently to check for changes in source content; important when above is set to 'manual'.

This allows you to configure the frequency in which Smartling will check your Connector for source content changes. If you would like Smartling to change the default frequency of 3 hours, insert your required cron frequency into this field.

3 hours is the recommended shortest time duration between checks.

Cron

Polling schedules work off cron expressions. Cron-Expressions are strings that are made up of sub-expressions. These sub-expressions are detailed with a value and separated with white-space. The sub-expressions represent the following components;

Sub-expressions

Valid Value

Related Special Character

Seconds

0 to 59

-

 

Minutes

0 to 59

/

-

,

Hours

0 to 23

/

-

,

Days-of-Month

1 to 31*

/

-

?W

Month

0 to 11


/

-

,

Day-of-Week

1 to 7**
MON-FRI

MON,WED,FRI

MON-WED,SAT

*
/

-

,
?
L

#

*depending on the month. If the month has only 30 days, then use values 1-30.

** Sunday is 1

For more on cron expressions and special characters, including some examples, see here.

Special Characters in Cron Expressions

  1. * is used to say “every” possible value of this field.
  2. / can be used to specify increments to values. For example, if you put ‘1/1’ in the Days-of-Month field, it means ‘Daily’.
  3. ? is allowed for the day-of-month and day-of-week fields. It is used to specify “no specific value”. This is useful when you need to specify something in one of
    the two fields, but not the other.
  4. L character is allowed only for the day-of-month and day-of-week fields. It means “last”, for example, L in the day-of-month field means “the last day of the month”
  5. W is used to specify the weekday (Monday-Friday) nearest the given day. For example, if you were to specify “15W” as the value for the day-of-month field, it would mean “the nearest weekday to the 15th of the month”.
  6. The # is used to specify “the nth” XXX weekday of the month. For example, the value of “6#3” or “FRI#3” in the day-of-week field means “the third Friday of the month”.
  7. - is used to specify ranges. For example, “10-12” in the hour field means “the hours 10, 11, and 12.”
  8. , use comma-separated values to specify additional values. For example, “MON,WED,FRI”.

Talk to your Solutions Architect about building and testing your own cron expressions from here before inserting them into your Smartling Connector Configuration.

Content Parsing

When Smartling captures content from the connecting platform, it may process the fields of an entry based on your configuration settings and may break down the individual fields into even smaller strings for translation. This process makes it easier to produce higher quality translations faster.

Follow the steps below to configure how Smartling should handle fields based on how your content editors are allowed to format them in the connecting platform. Smartling supports plain text / markdown, HTML, and Connector Rich Text. Of course, if a field is not "localizable" in your content model, then it won't even appear in the list of fields for that content type in the Smartling settings.

Parsing Option

Description 

Copy source 

Copies the source content to the target field.

Do not translate

Use this if the field shouldn't be translated using Smartling.

Examples are fields that contain localizable metadata such as a JSON field that contain GPS coordinates, or a URL that is used for your application. 

Markdown

Parses Markdown tags similar to HTML tags for the best experience by translators and maximum Translation Memory leverage.

Use this when your field is likely to have markdown.

Plain text

All text and characters treated as plain text.  

Use this for fields that you expect to only have plain text with no markup or formatting.

HTML

Parses the field's HTML tags for the best experience by translators and maximum Translation Memory leverage.  

Use this when your field is likely to have HTML markup in it

Rich Text

Only available if the field is Rich Text.

Use this to capture the content for translation using are custom rich text parser for your connecting platform.

ICU Parses text in the field as ICU MessageFormat.
Use this if the fields contains plural-sensitive content.

By default, Smartling will assume that content is formatted as plain text / markdown.

Learn more about content parsing here.

Smartling Settings

The Smartling Settings section of the configuration allows you to decide how you want your content sent to and delivered from Smartling. This will only be visible to your Customer Success Manager and Solutions Architect to configure, but below are some considerations for you to discuss with them.

Auto authorize (if applicable)

Configuration: On/Off or authorizeContent = true / false

Enabling auto authorize will submit content from your connecting platform to Smartling and authorize it for translation in a DailyUploads ‘bucket’ job, at a frequency defined in the Polling Schedule field below. This automated option requires fewer resources in your translation process and can save time in ensuring translations are initiated and completed automatically.

If you decide not to enable auto authorize, you will require additional resources in an internal Smartling user, but with that comes more control over your content translation.

Talk to your Solutions Architect about if this feature is right for you.

Retrieval Type

Once auto authorize is enabled, you can decide what state you want to retrieve the translations in from the following options;

  • Published: send only published translations to the connecting platform
  • Pseudo: send pseudo translations to the connecting platform, so you can view the potential layout of your translated asset. This setting is recommended during testing periods.
  • Pending: send any available translations to the connecting platform, meaning all published and saved translations. This can lead to frequent overwriting of translations in the connecting platform which may be problematic for some content types, such as email content, as translations will not be updated after the asset has been sent from the connecting platform.

Smartling Namespace (if applicable)

A namespace is an attribute of a string used in deduplication and is set by default to the file URL. This means that the same text uploaded in different files, even with the same variant values, will be considered different strings in Smartling. This is recommended when you have multiple developers who need to translate the same resources file in different code branches, or if two pages have the same sentences and both require translation separately. See Strings for more details.

If your Connector configuration has a Smartling Namespace field, you can choose how you want this configured from the following options;

No Versions

Each string from the file will have namespace equals to file_uri of a file, meaning each file will have unique strings, but will not be versioned over time. Namespace and fileUri will be the same.

Directive applied by the Connector: smartling.file_uri_as_namespace = true

Account

Files are uploaded without any explicit setting for a namespace, and so it will revert to the account default configuration. File API will read account\project file parsing template and implicitly will add a namespace configuration.

Directive applied by the Connector: none

Share all

Files are uploaded without namespace, resulting in strings shared across all files in the project. No versioning of files. Although not commonly used, it is available because some accounts require strings to be shared this way.

Directive applied by the Connector: smartling.file_uri_as_namespace = false

File Versions

This configuration results in string sharing across versions of the same file. Namespace is created automatically.
Each time a translation request is made, a new version of the file is uploaded using file versioning in the URI for its unique fileUri.

Directive applied by the Connector: smartling.namespace = <connector dependent asset key>

Placeholder Format

Placeholders represent dynamic variables, such as names, discount percentages, or monetary amounts, that should not be translated but need to be included in your translated content. There are many ways to format placeholders, depending on your file format and content.

Talk to your Solutions Architect about the best way to format placeholders within your Connector.

Considerations

Translations are returned once 100% of authorized strings are translated into the target language. If source content is found in the translated asset, this may be because that content is in Awaiting Authorization in Smartling. To ensure all content is translated in the target language, authorize all strings for translation.

To automate this process

  1. Go to your Smartling Hosted Connector project
  2. Click on Project Settings > Hosted Connector Settings
  3. Click the resubmit changed content dropdown, and select Auto
  4. Additionally, enable Auto Authorize

Was this article helpful?