Mindtouch Connector Overview
Mindtouch is a knowledge base platform. The Mindtouch Editor is a familiar interface that’s easy to use for contributors across the organization to create valuable and intuitive product documentation.
Smartling’s Mindtouch Connector ingests your Mindtouch content into Smartling, allowing you to authorize this content for translation from within the Smartling platform. The Mindtouch Connector collects your translatable assets into a package, processes that package for translation, and automatically delivers translations back to Mindtouch, once complete.
You should have a separate Mindtouch instance for each target language you are translating into. Translated content is delivered to its respective Mindtouch instance, when the asset file is translated (not when the Job is complete).
Simplified, dynamic HTML Visual Context is supported.
Smartling’s Mindtouch Connector currently ingests all assets and child assets* within the following Mindtouch content types:
- Articles (published only)
*Related assets captured 1 levels deep. However, parent assets must be translated in order for related assets to be captured for translation.
How the Mindtouch Connector Works
The Mindtouch platform has a limitation that prevents multiple processes from running concurrently on their servers. This means that if a process is already running on the Mindtouch server, while the Mindtouch Connector attempts to make a new request for a source zip package or to deliver translations, the Mindtouch Connector will fail.
Unfortunately, there is no queue mechanism on the server to queue up the request if one is already running. This means that the Smartling user will have to manually reattempt the request again, once the initial process has been completed in Mindtouch.
Due to this limitation, the Mindtouch Connector exports Mindtouch articles as packages for translation. These are zipped packages that can also be exported from your Mindtouch instance. When you request translation in Smartling, the Mindtouch Connector requests these zip packages from Mindtouch as automatically uploads them to Smartling for translation. The Mindtouch Connector also tracks the states of these Mindtouch packages as they move from Mindtouch to Smartling for translation, and from Smartling back to Mindtouch.
Important things to know about Mindtouch packages:
- There is a 1:1 mapping between the Smartling Job and a Mindtouch Package
- The status of the package is completely separate than the status of the Smartling Job
- There is a Source and Target package that have separate statuses
- Translations are delivered when the asset file is translated, one file import at a time
- A Mindtouch Connector Project in Smartling with all target languages configured in the Language section of the Project Settings
- A Mindtouch instance (site) for each target language you are translating into (one instance per language)
- Consult your Customer Success Manager / Solutions Architect with the following information for each Mindtouch site for each language:
- URL - host of your language Mindtouch site. For example, the source site could be https://mysite.mindtouch.us, the French site could be https://mysite-fr.mindtouch.us
- Username - valid Mindtouch username. This user must exist on all Mindtouch sites (source and each language sites). The API request will be handled from this user identity. For more information, read the Mindtouch documentation.
- Server API token - each API token has a “Key” and a “Secret”. The Mindtouch Connector required both to complete configuration. For more information, read the Mindtouch documentation.
Mindtouch Asset List
Once you have connected your Mindtouch account, you will find Mindtouch content in the Mindtouch tab in your Smartling project. Here you will see a flat list of your Mindtouch Article assets.
The Asset List will include the following columns:
- Name: the title of the asset in Mindtouch
- Smartling Status: the asset's translation status in Smartling
- Article Type: the content type as listed in Mindtouch
- Package Status: the status of the entire Mindtouch package
- App Link: brings you directly to the asset in Mindtouch
As you navigate through your article content in Smartling, above the Asset List will display the hierarchy breadcrumb. The breadcrumb is a representation of the current position in the Mindtouch hierarchy and structure for articles. This breadcrumb will update as you navigate within the structure.
Use the breadcrumb to navigate back a level in the hierarchy.
The package status could be one of any of the following:
- Pending Smartling Upload: This is the initial state for the translation process. It means a Smartling user has just requested translation of a Mindtouch asset.
- Requested zip: The export job was created in Mindtouch. The Mindtouch Connector is waiting for Mindtouch to deliver the zip package containing source content.
- Downloading zip: The Mindtouch Connector has received the Mindtouch export job ID and Smartling Job UID and ready to download zip package with source content.
- Smartling Uploading files: The Mindtouch source zip package is saved locally, and the Mindtouch Connector is ready to upload source files
- In Progress (Uploaded): The Mindtouch Connector has uploaded all source files to Smartling Job
- Delivered: The Mindtouch Connector has successfully delivered all translations for all languages.
- Failed: There are three possible reasons for this status:
- If Smartling cannot parse the source zip package
- If one or more file upload failed, then the entire package failed
- If at least one locale was not delivered successfully (e.g. The Mindtouch Connector cannot download a translated file from FAPI or can’t create Import job in Mindtouch)
Click the information icon beside the asset name, to access the Asset Details page. Here you can see further information on that asset, including the translation status for each language.
If the asset has linked entries, or related assets, you can view the related asset, and it's translation status under Linked Entries.
You can sort the asset list by Mindtouch structure (default) or by asset name.
Search & Filters
The Article Type filter is a dropdown menu of all the article types listed in your Mindtouch instance.
The Mindtouch Status filter currently only supports Published content. Draft content is not ingested into Smartling for translation.
The search box in the Asset List works allows you to search by asset title.
You can only search for one asset at a time; comma-separated search is not supported.
Completed: Translations were successfully delivered from Smartling to Mindtouch.
Draft: The asset is in the process of being sent for a new translation request. For example, if changes were made to the source content and your Mindtouch Connector is configured to automatically send the new content for translation. The asset could be sitting in submission queue or sitting in Awaiting Authorization
Failed: The asset submission failed, or the translation delivery failed. A number of reasons can result in a failed status, but some of the most common are due to invalid regex causing placeholder issues, or the target languages are disabled in Mindtouch.
In Progress: The asset has been successfully sent to Smartling from Mindtouch, and the translation process has commenced but is not yet completed. If there is a case where translations are complete, but a network issue occurs, the translations will remain in progress until the Mindtouch Connector delivers the translations to Mindtouch on a successful retry.
Translated: The asset has been translated in Smartling and is now at a Published state in the Smartling dashboard, however the Mindtouch Connector has not yet delivered the translations back to Mindtouch.
Not Translated: The asset has never been submitted for translation.
Filter by the dropdown list of target languages configured in Smartling for the Mindtouch project. Target Languages must also be configured identically in Mindtouch and mapped in the Mindtouch Connector Language Configuration found in your Smartling Project Settings.