🔗 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. 
• Translations should not be added directly in your connecting platform, and all translation edits should be made in Smartling. 

*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 certain 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.

Can I request translation in bulk?

Yes, you can request translation in bulk by navigating to the connector tab, and selecting the checkbox next to each asset you wish to translate. You can also request content in bulk using the Select all matching current filter. 

When you request assets in bulk using Select all matching current filter, you cannot individually select or deselect specific child assets (if the hosted connector you’re using supports requesting related or child assets). If you would like more control and visibility over which related assets are sent for translation, please select multiple assets manually using the checkboxes, rather than using the Select all matching current filter option. 
Example: 

If you select 30 or more assets for translation, the Request Translation wizard will close after Step 2 and the list of bulk requests (Recent Job Processes) will be displayed. This is because uploading a large number of assets can take some time, and the connector uses a different service to process and upload large sets of assets. 

The number of bulk requests submitted is displayed on the top right of the page. You can check the status of the bulk requests by clicking the number icon. 

Example: 

This will open the Recent Job Processes window where you can view the details and status of each bulk job request. You can cancel any incomplete job requests by clicking the ellipsis menu under Actions > Stop Process. 

How can I add languages to a job?

To add languages to a job, request the asset(s) for translation in the additional language(s) via the connector tab in the project. Unlike typical file projects, languages cannot be added directly from the job. When requesting assets in new languages, you can choose to add the content to an existing job or create a new one.

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. For example, once all French strings for a file are fully published, French translations are delivered. This means that all strings for a file must be either published or excluded for delivery to occur. If any strings for a specific locale remain in awaiting authorization, translation delivery for that locale will not be triggered.*

Example

An asset is requested for translation and contains five strings. The content is added to Job A, and the strings are authorized for translation into Spanish. Later, new content is added to the same asset and requested for translation again, adding two new strings for Spanish to Job B.

If the strings in Job B remain unauthorized and are in awaiting authorization, the Spanish translations will not be delivered until those strings are authorized and published. All strings in the file for Spanish (across both Job A and Job B) must be completed and published to trigger translation delivery. If you do not wish to translate certain strings, they should be excluded from translation.

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. In rare cases, translation delivery may be triggered even if not all strings in a file are published, depending on your project configuration. Translation delivery relies on file callbacks. If you have questions about your project’s callback settings, please contact your Customer Success Manager or another Smartling representative. 

My job is completed, but I don't see translations in my platform. Why? 

Smartling hosted connectors are file-based, meaning translation progress is monitored at the file level rather than the Job level (except for Smartling’s GitHub Connector, which is Job-based). Content from your connected platform is bundled into a file and sent to Smartling. Once a file is fully translated for a target locale, the translations are automatically delivered back to your platform.

If a Job is completed, it doesn’t necessarily mean the asset is fully translated and successfully delivered. The connector does not track Smartling Jobs—it only monitors progress and delivers translations at the file level.

Follow these steps to understand what’s happening with your content. You can also find a video tutorial in the Smartling Community.

1. Check the Translation Progress. 
   Within the connector tab of your project, locate the asset and click the info icon to open the Asset Details page. 
   
   Example Asset Details Page
   
   

   • The colored progress bar indicates the Translation status:
     ‣ Green = All strings for that locale have been translated and published in Smartling.
     ‣ Purple = Some strings are still In Progress. 

   If strings are still In Progress, click on the locale name to open the content in the Strings View. Use the Status filter to check the In Progress strings. Then, check the Job column to see which Jobs(s) contain the strings. An asset's strings can be spread across multiple Jobs, and all strings must be published for the translation status to turn green. 
   
    

2. Check the State.
   The State column refers to the connector status. Once the Translation progress is green for a locale, the connector begins the translation delivery process.  
   • ✅ If the delivery is successful, the State column changes to Completed, and the Delivered column will display the date when the translations were successfully delivered. 
   • ❌ If the delivery fails, the State column shows Failed. Hover over the Failed message to see the reason for the failure. 
      

Possible causes & fixes for failed status 

1. The connecting platform's API rejected the translated strings due to: character limits, invalid characters, removed/added HTML tags, other validation errors, etc. 

   🔄 Fix: Correct the problematic translations and re-request the asset for translation to re-trigger delivery. 

2. A rate limit has been exceeded (controlled by your connecting platform). 

   🔄 Fix: Click the Export button to manually re-trigger translation delivery. 

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 a limited number of 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. 

Adding and editing translations

Translations should not be added directly in your connecting platform, as the connector does not recognize translations added manually. If your team adds translations directly, they will be overwritten when the connector delivers translations.

If you need to edit translations after they have been delivered, all edits should be made in Smartling. The connector does not track or recognize changes made directly in the connecting platform. Any edits made in the connecting platform will be overwritten the next time the connector delivers translations for an asset. To ensure changes are preserved, always make edits in Smartling.

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. 
  •