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;

• Setting up a Connector Project in Smartling
• Connecting the platforms with Oauth
• Language Configuration Settings
• General Settings
• Understanding Cron
• Content Parsing Settings
• Smartling Settings
• Considerations
• Best Practices

Here is a list of some of Smartling’s Hosted connectors for which this article is relevant.
For full details, visit the documentation for the specific Connector you are intending to use.

• Akeneo
• Braze
• Contentful
• Contentstack
• Episerver
• Google Drive
• HubSpot
• Iterable
• Marketo
• Mindtouch
• Oracle Eloqua
• Salesforce Marketing Cloud (SFMC)
• Salesforce Knowledge
• Sanity
• Yext
• Zendesk

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

Step one in setting up a Connector in Smartling is always to 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 have 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.

We recommend that you do not combine Jobs Automation rules with automation of prior requests for translation settings, as doing so may result in unexpected behavior.

Changed Content Behavior Frequency (Admin only)

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 at 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:

Connectors use UTC (Coordinated Universal Time) for cron expressions.

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. The latest version of the source is always delivered as the target. If the connecting application supports versioning, a new version of the translated file is created on delivery.
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 (i.e. one file version). Namespace and fileUri will be the same. Re-uploaded files are overwritten.

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 with a shared namespace and 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

Search and Filter Content

When you navigate to the Connector tab of your project, you can view all assets pulled in from the external platform you are integrating with (e.g., Contentful, Zendesk, Marketo). The connector retrieves this list of assets via the external platform's API. On the left side of the page, there is a list of connector filters called "[Name of connector] Filters". When you use one of these connector filters, the connector sends a request to the external platform's API and then displays the list of matched assets returned.

Below this section is another group of filters called "Smartling Filters". Smartling filters work differently from the connector filters because external platforms have no knowledge of statuses and languages in Smartling. Therefore, the connector must first retrieve all assets from the external platform and then filter them based on the Smartling filter(s) selected. Often, a spinner icon will appear because the connector is making tens of API calls to retrieve all assets. Depending on the number of assets present in your external platform, it may take some time to load all the assets matching the Smartling filter criteria.

If the search times out, you will see a Continue Search button. If you wish to continue searching for matching assets, please click Continue Search until the connector has been able to load and filter all assets. Please note that this may require clicking the Continue Search button multiple times. 

Whenever possible, we recommend narrowing the scope of the search by using the connector filters. This will help speed up the search process. If you need to re-request translation for all assets with a particular Smartling status, you can use bulk request option "Select all matching current filter" which will handle the entire asset retrieval, filtering, and requesting process. 

Best Practices

To ensure that your connector is providing the highest level of automation and efficiency, make sure to review your connector settings with your assigned Customer Success Manager or Solutions Architect.

Some best practices to remember for connector settings:

1. Locale Mapping
   
   
   • It is important to ensure that each of your target locales is mapped correctly and that the locale matches exactly what is identified in the connector.
   • Whenever you add a new language to your connector project, don’t forget to map it accordingly.
     
     
2. Automation of Prior Requests for Translation
   
   
   • Some connectors allow for the identification of updates to source copy, and it is important to adjust these settings based on your needs.
   • For a fully automated process, set it to “Auto”, so the connector detects changes to your source content every 3 hours. Any changes detected are automatically batched into a job and can be set to await manual authorization, or can be auto-authorized.
   • For more control over what updated copy gets submitted for translation, set it to “Manual”. This setting will still allow the connector to detect changes to your source content every 3 hours, but instead of batching it into a job, it will flag any content as “outdated” so you can choose what to submit for translation at your discretion.
     
     
3. Auto-Authorize

• One of the key benefits of a Smartling connector is the ability to automatically authorize new content or updated source copy for translation.
• When the Auto-Authorize setting is enabled, the connector automatically authorizes any jobs in the pre-defined default workflow for each language.
• This setting can increase time savings, but if you need to closely regulate your translation budget, then you may want to consider disabling this setting, so you have more control over what content is getting authorized.

Video Tutorial: Translating with a Hosted Smartling Connector

This video shows how the translation process works with one of the following Smartling Connectors: Contentful, Contentstack, Eloqua, Episerver, Salesforce Knowledge, Salesforce Marketing Cloud, Sanity.io, Yext, Zendesk.

Timestamps:

What is a Connector? 00:07
How does it work? 00:45
How to get started 01:47

How to send content for translation 03:21
What your Linguists see 06:47

How to download completed translations 07:22
Exporting translations manually 07:46

What happens if the source copy gets updated? 09:09
1. Job creation for updated content: Auto ("Daily bucket" jobs) 10:02
2. Job creation for updated content: Disabled 12:29
3. Job creation for updated content: Manual 13:03
Which setting is best for you? 14:42

Connector Settings:
How to add a new language: Language Configuration 15:14
How to add a new content type: Content Parsing 16:43

Help & Support 17:56