🔗 Connectors 101: Overview of Hosted Connector Behavior

 

The following article describes the standard behavior among Smartling Connectors, particularly Smartling’s hosted Connectors. This information serves as an overview of common Connector behavior.

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 articles on each Connector.

The information in this article applies to some of Smartling’s most popular Connectors, including Contentful, Zendesk (Guide), HubSpot, Salesforce Knowledge, Salesforce Commerce/Marketing Cloud, and Marketo.

Key Points

• With hosted Connecters, the content to be translated is not uploaded to Smartling until a user or Connector automation requests the translation of the asset. 
• Connectors (excluding the GitHub Connector) are file-based, meaning translation progress is monitored at the file level rather than at the Job level. Translation delivery occurs automatically when a file is fully translated for a target locale.*
• Hosted Connectors monitor any changes to source assets, including changes to non-translatable content. When changes are detected, but there are no changes to the translatable text, the Connector automatically re-delivers translations to ensure all changes are synchronized with the connecting platform. 

*See note below. 

When Are Assets Uploaded to Smartling?

Hosted Connectors have access to the content in your connecting platform. When you navigate to the Connector tab of your project, you can view all the assets the Connector sees. Assets are not actually uploaded to Smartling until they have been requested for translation. Once an asset has been requested for translation, the content in your connecting platform is bundled into a file and uploaded to Smartling, where it is parsed into Strings.

The Connector tab displays the name of the Connector. 

Do Jobs Automation Rules Work With Connectors?

Standard Jobs Automation Rules cannot be used with Connectors.* However, there are Connector-specific Jobs Automation Rules that can be used with the Mindtouch and Contentful (Fields) Connectors. See Automation Rules For Connector Content Translation. 

*The Repo Connector(a non-hosted Connector) is the only exception and is compatible with standard Jobs Automation Rules.

How Do Connectors Monitor Translation Progress? 

When you request an asset for translation, the content from your connecting platform is bundled into a file which is sent to Smartling for translation.

Smartling Connectors are file-based, meaning translation progress is monitored at the file level rather than at the Job level (excluding Smartling’s GitHub connector which is Job-based). Once a file is fully translated for a target language, the translations are automatically sent back to your connecting platform. 

If a Job is completed, it doesn’t necessarily mean an asset is fully translated, as an asset’s content can be spread across multiple Jobs in Smartling. For example, this may happen if the source asset is updated and the new or updated content is uploaded to a different job from the original content.

What Triggers Translation Delivery?

Translations are automatically delivered once all authorized strings for a file are complete for a target locale. (e.g., French strings for a file are fully published → French translations are delivered).*

Hosted Connectors will also deliver an asset’s translations in the following scenarios:

• A String was re-translated or a published translation was updated. 
• An asset is re-requested for translation, and all translations for that asset are complete.
• Visual context associated with a String was added.
• The source asset was modified in your connecting platform. 
• An asset’s translations were manually exported from Smartling. 

*This is the default behavior. There are rare cases when translation delivery is triggered even when not all authorized strings from a file are published, depending on your project configuration. Translation delivery relies on file callbacks. Contact your Smartling Representative if you have questions about your project's callback configuration.

How Connectors Monitor Changes and Re-Deliver Translations

Re-delivery can occur when:

• An asset is re-requested for translation.
• The source asset is modified in your connecting platform.

Smartling hosted Connectors monitor any changes to your source content. This includes changes to translatable text and any changes to the content in general, including non-translatable content, asset properties, or metadata. When changes are detected, but there are no changes to the translatable text, the connector automatically re-delivers translations. This is done to ensure all changes are synchronized with the connecting platform.

Technical Details on How Connectors Detect Changes

• After each successful upload, Smartling calculates a hashcode for the file content and saves it in the database. The JSON file that is uploaded to Smartling is used for the hashcode.
• A cron task (on Smartling’s side) or a webhook from the connecting platform initiates the “detect changes” feature. It creates a new JSON file using the current asset content and calculates a new hashcode. It does not upload the file; it simply creates it and calculates the hashcode.
• If the new and old hashcodes differ, the Connector will re-upload the asset.
• Regardless of the translation status, the Connector sets the asset status to “In Progress.” If there are no new strings and all translations are already published, the Connector will deliver what was just uploaded to push the status from "In Progress" to "Complete". This means the Connector will re-deliver the translated content to your connecting platform.
• If there is new content for translation, the content will be automatically batched into a Daily Bucket Job (which may or may not be auto-authorized) based on your project’s automation settings. The asset status will be “In Progress” regardless of whether it has been authorized for translation yet. If no automation is enabled, the asset will be marked as “Out of Sync,” and you will need to manually request the asset for translation to translate the new content. 

Settings That Impact How Often an Asset Is Requested for Translation

The following settings can impact how often an asset is requested for translation and thus how often the Connector re-delivers translations: 

• Automation of Prior Requests for Translation: Determines how you want Smartling to handle changes to the source content for items that have been previously requested for translation.
• Include Related Assets: Some Connectors allow you to automatically include related assets. If "Include Related Assets" is enabled, when one source asset is updated all related assets will also be re-delivered.
• Connector Jobs Automation Rules: (only applicable to Contentful(fields) and Mindtouch Connectors) If a Connector Job Automation Rule runs and an already translated asset is re-requested, the Connector will re-deliver translations. 

What if an Asset Contains No Translatable Content?

If an asset contains no translatable strings, the Connector does not create a file for the content when it is requested for translation. In the asset list of your Smartling project, the asset will have the status "Failed". This may happen when related assets are included for translation, but not all of them actually contain content to translate. 

Example Scenario (Contentful Connector)

Page entry (contains one or more translatable fields)

Related Assets:

  Menu entry (entry that has a bunch of references, but contains no translatable
  fields)

  MenuItem1 entry (menu item with label, URL, and other translatable attributes)

  MenuItem2 entry (menu item with label, URL, and other translatable attributes)

If thePage entry is requested for translation along with its related assets, the Connector will attempt to upload all four entries, but only three of them contain translatable content. As a result, the Connector will never update the Menu entry with any translations, as it does not contain any translatable content. Translations will only be delivered for Page entry, MenuItem1, and MenuItem2. 

Considerations 

If you want to prevent a hosted Connector from re-delivering translations too often, you can consider: 

• If you have Connector Jobs Automation Rules enabled, reconsider how many levels deep the Connector should scan for related assets, or turn off "Include Related Assets" entirely. It may reduce the number of re-uploaded assets. 
• Consider changing Automation of Prior Requests for Translation, from "Auto" to "Manual" or "Disabled".
• Assess your connecting platform to see if some automation or user is modifying the source assets after they have been translated.