Transifex's Zendesk integration is available as a paid add-on, please contact us to enable Zendesk for permanent usage or a 15 day free trial. Additionally, you’ll need to be on Zendesk’s Guide Professional plan with Support Professional or Enterprise, as only those plans support multilingual content.
With the Zendesk integration you can synchronizes Help Center content and finished translations between Zendesk and Transifex. Use this integration so that your localization team can leverage the most of Transifex services while translating your Help center.
In this guide you will see how to:
- Authenticate Zendesk to your Transifex organization
- Configuring your Zendesk Help Center to support multiple languages
- Linking a specific Transifex project with Zendesk content
- Translating content in Transifex
- Syncing content localized in Zendesk to Transifex
- Syncing content manually
- Reading the syncing status report
- Handling language mapping between Zendesk and Transifex
- Editing the Transifex Project - Zendesk content link
Compatibility with Zendesk 1.0
If you are using the previous Zendesk integration implemented as a Zendesk app called Transifex sync, please note that it is discontinued and will not be maintained any further. It is highly recommended switching to the new integration. Read more on switching to the new integration here.
Integrating Transifex with Zendesk will enable all your Transifex project maintainers to sync content between Zendesk and their projects in Transifex.
In order to connect your Zendesk and Transifex accounts you need to be a Transifex administrator and follow the steps described below:
When creating the project, be sure to:
- Visit your Transifex organization settings
- From the Left-hand Side Menu that appears, select Manage Integrations
- Enter your main Zendesk subdomain in the respective input box and press Authorize. By connecting your main Zendesk subdomain you provide access to all available Zendesk subdomains and brands in your Zendesk account.
- You will be redirected to Zendesk for authorizing the integration with Transifex.
Authorizing integration with Transifex and getting back to Organization settings > Manage integrations you will see the respective Zendesk integration box as active. This means that the integration is now active and you can start syncing content between Transifex and Zendesk.
By default, your Zendesk Help Center only supports one language. You have to configure it to support additional languages. There are two places you have to do this: the Support Agent, and the Help Center.
From your Zendesk Agent, click on the Gear icon to go back to the Admin area.
Under SETTINGS, select Account, then click on the Localization tab.
Set your default language from the dropdown. This should be the same as the source language you set for your project in Transifex.
Click Additional languages and select the languages you want to offer your Help Center in. They should match the target languages you chose when you created your project earlier.
Click Save tab.
Next, we’ll repeat the same setup inside the Help Center:
From the top menu bar of the Agent, click on the windows/grid icon on the right. Then click on Guide.
Click on Guide admin in the top menu bar.
Click on the Gear icon in the left menu to go to the Language Settings.
Scroll down to the Additional languages section of the page and select the same set of languages as before.
Hit Save at the top of the page to save your settings.
Navigate to the project of your choice or create a new project and visit the Project settings page. In there, you will see a tab reading Integrations.
If the integration is set up as described in the previous step, you will see the Zendesk option along with a button to Link Help Center. Clicking on that button, the Zendesk Integration wizard will pop up to manage the setup.
On the first step of the wizard, select the Zendesk subdomain that holds the content you want to sync with the project for localization.
Keep in mind that only subdomains with a Help Center set and multiple languages enabled will be displayed in the list. If you don’t see your subdomain in here please follow the instructions on Configuring your Zendesk Help Center to support multiple languages. When you are done with this step, hit Next to choose the Zendesk content you want to sync with Transifex. The content currently synced between Zendesk and Transifex includes Articles, Dynamic Content, Categories, and Sections. In the wizard interface shown you have the ability to view content per content type supported and search across Articles and Dynamic Content. When you identify Zendesk content that you want to sync to your Transifex project, mark it by checking the box on the left of the content title. Any selections that you have made are persistent so you can keep searching and navigating on the displayed content list without losing your selections. You can learn more about the functionality on this wizard’s step by checking the respective section to Choose content for translation, below.
When you are done with selecting your content. Click Next to move to the final step of the setup wizard, where you will define how the syncing between Transifex and Zendesk will happen.
Pushing of content back to Zendesk happens automatically based on your selected criteria; upon 100% translated, reviewed or proofread content.
For dynamic content, you will get an option to split it into phrases. This is very convenient for cases where dynamic content is hosting Zendesk macros that you use for your emails. Please note that this option can be set only during the first setup of the integration, you will not be able to change it later on.
When you are done with this setup step click Save & Synchronize to start syncing content from Zendesk to Transifex.
Some steps described above are also accessible when you want to update the integration settings. Check Editing the Transifex Project - Zendesk content link section below for more.
All Zendesk content that is synced for the first time with Transifex will also sync any existing translations into the newly created resource as long as the option "Fetch initial translations from Zendesk" is enabled.
1) if the option is unchecked, we always ignore translations found on Zendesk, and never send them to Transifex
2) if the option is checked, it works as follows: every time content is synced from Zendesk to Transifex, the integration checks each resource/language separately and if this language for this resource is completely empty (there are zero translations), we then take the translated content from Zendesk and send it to Transifex. If, on the other hand, there is even 1 translation on Transifex for this resource/language, we consider Transifex to be the source of truth, so we ignore the Zendesk translations for that resource/language and do not send them to Transifex
This includes content detected during the setup of the integration or new content detected on a subsequent sync. Any syncing actions on content that already has a resource in Transifex will not include translations updated on Zendesk. Check Syncing content localized in Zendesk to Transifex for more.
In this subsection we are expanding on the full functionality provided on the content selection step of the wizard.
On this step you will see information about Zendesk content found on the subdomain you have linked to the specific Transifex project. More specifically you will see a list of either:
- Dynamic content
When content is selected a ribbon appears at the top of the list informing on the total selected items. Select or deselect content at will and the item counter will update accordingly. There is also an option to clear the whole selection using the quick action Clear Selection which appears in the ribbon area.
For each item in the list you can see some additional information depending on the sync status for that content:
- The title is a link to the content in Zendesk
- Checked if content is selected to sync between Zendesk and Transifex, unchecked otherwise
- There is a link to the Transifex resource hosting translations of content with an icon at the end of the row:
If the content in Zendesk is in a draft state, the title of the content will have a badge like this:
An Updated at field holding the date of the last update of the content in Zendesk.
To filter contents displayed in the list choose the dropdown to select content type and type in the search box that is available for articles and dynamic content. The contents list will be filtered either pressing the Enter key or the Search button. Any term typed for search will look into articles or dynamic content title and context. To clear out a search term delete it and press Enter key or the Search button, alternatively you can use the X icon displayed in the search area.
Items in the list have pagination, you can change the page size using the dropdown displayed under the contents list and navigate through the different pages using the left and right arrows located in the same area, under the contents list.
The synchronization wizard allows linking of the current project in Transifex with a brand (subdomain) in Zendesk. This can be done in the first step of the wizard when creating the integration in the project settings.
The brands allowed to be selected are those that have an active Help Center in Zendesk, if you want to link a brand without Help Center activated, please follow the steps in this link.
Linking a Transifex project with a Zendesk brand/subdomain can only be set during the setup of the integration and cannot be changed in subsequent edits. The only way to change the brand is to unlink the project from the current brand and start over with the project integration.
If you are using complex dynamic content to create macros, there is an item in the synchronization options to split long content into separate sentences. This is called String segmentation. You can only set this option on the integration setup as all synced content will be handled differently based on your setting.
Here is an example to showcase the result of the segmentation: In a case of dynamic content that contains 5 sentences, with the segmentation enabled 5 strings will be added in the source language resource, versus a single source string when the segmentation is disabled. In case where translations are available and the segmentation is enabled, the pre-processing manipulation will try to match every sentence in the translation with the respective string from the source language.
This match is not 100% fail-safe, and there are two possible drawbacks:
- Segmentation on the translation results in fewer sentences than the respecting sentences from the source language segmentation.
- The translation segmentation results in more sentences than the sentences created in the source language segmentation. In this case, the pre-process manipulation will gather all the unmatched translations into the last source string.
For both cases, it is suggested to manually move translations to the appropriate source sentences.
Syncing localized content back to Zendesk can work automatically per Zendesk content entry (article, dynamic content, category, or section) on each target language. The integration offers three possible options for automatically sending localized content back to Zendesk on:
- 100% translated
- 100% reviewed
- 100% proofread
Depending on the setting selection this will apply on individual content entries as they are localized on each target language.
For example, once an article is fully translated to French, the French article will be sent to Zendesk. If the Chinese translation of the article is not fully translated it will not be sent to Zendesk.
Keep in mind that translated content synced back to Zendesk will be available in your Help Center after approximately 4 hours. This is related to how Zendesk is rendering the Help Center and is out of the scope of the integration.
All content that is synced from Zendesk to Transifex will create a resource following the Zendesk content name. For example, if you have two articles in Zendesk titled “Getting started” and “Quick installation”, syncing them to Transifex via the integration you will get two resources with the exact same names “Getting started” and “Quick installation”. The Zendesk content type is passed as a resource category in Transifex, visible in the resources page. Especially for Zendesk articles the integration migrates Zendesk category and section as resource categories.
Once your content is inside Transifex, you have a number of translation options:
- Invite your translation agency or in-house team to work in Transifex using the Editor.
- Order translations from Transifex partners. The finished translations are delivered back to you inside Transifex.
- Crowdsource translations with your community.
- Machine translate using Google Translate or Bing Translator.
Syncing content from Zendesk to Transifex happens either upon saving or updating the integration settings on the project level.
When a syncing process is initiated, you will be able to see that syncing is in progress in your Project settings > Integrations tab inside Zendesk card. This process could take some time, depending on the number and size of the files that are syncing.
At this time the integration does not automatically detect updated content on Zendesk. If you want to force a sync from Zendesk to Transifex.
If you want to re-sync existing contents from Zendesk to the respective resources in Transifex, then you should click on Edit Settings in the project integration in order to show the Integration Wizard, then push the Synchronize & Save Settings button in order to start a new sync process. If you want to add new contents for synchronization, then repeat the same process described previously, but before pushing the Synchronize & Save Settings button, check all the new contents you want to sync.
Keep in mind that the integration works on top of the HTML file format which is quite an unstructured file format. Syncing translations from Zendesk to Transifex please keep in mind for differences in structure and order of translations as it might affect the mapping of translations to the proper strings.
For more details check Managing HTML translation files.
There is an option to send localised content to Zendesk manually, without waiting for a resource to be 100% translated or reviewed. There is a Send to Zendesk option available on the Projects settings > Integrations tab in the Zendesk card.
By clicking on Send to Zendesk a modal will appear requesting for the threshold localisation percentage that Transifex will check on all your project's resources.
All target languages that are localised above that threshold will be synced with Zendesk using the Sync content options you have set up for the integration. For example, if you had set up Zendesk to Sync 100% translated resources, the manual process will identify all target languages whose translation percentage is equal or above the threshold percentage you set on the modal and sync all content back to Zendesk.
Keep in mind that translated content synced back to Zendesk will be available in your Help Center after approximately 3 minutes. This is related to how Zendesk is rendering the Help Center and is out of the scope of the integration.
Syncing less than 100% translated content to Zendesk might result in parts of the content being in the original language for that Article or Dynamic Content. When that content is fully translated in Transifex and synced back to Zendesk this issue will be eliminated.
In order to check the latest synchronization results, either from Transifex to Zendesk or from Zendesk to Transifex, there is a popup that shows the relevant information of each process, the syncing status report dialog.
To view this modal head over to your Project settings > Integrations tab and click on the more... link next to the Last sync status in the Zendesk card.
When the modal opens, you will see the latest activity in the Transifex to Zendesk or Zendesk to Transifex sync direction. For each of the two sections you will see directly on the title when the last syncing took place as well as an indicator for syncing errors.
In case a syncing direction doesn’t have a syncing status yet, an explanatory message will appear on the right side of the tab letting you know that there is nothing to report.
Expanding each section you will be able to see:
- A summary of the syncing status including, about content received from or send to Zendesk along with a breakdown by content type, a summary on languages that were synced
- A list of errors in sync along with details on the error that prevented syncing for that content.
It is worth noting that you will see details about the most recent syncing action between Transifex and Zendesk and not a full sync log for all attempts. Each sync action will attempt to sync all out of sync content, so any syncing errors that were previously found will either be repeated or fixed.
As your Help Center evolves, you might want to either extend the Zendesk content you are syncing to Transifex or change the workflow of pushing localized content back to Zendesk. To edit your options visit your Projects settings > integrations tab and click on the ellipsis in the Zendesk card, then Edit Settings. The interface to make the changes is the same as the one of the initial setup, but you will only be able to:
- Update your selected Zendesk content to sync with Transifex
- Change options on how updates from Transifex are sent back to Zendesk.
Please note that if you deselect already synced Zendesk content, the associated resource(s) will no longer be synced with Zendesk. Also, that resource in Transifex will not be deleted.
The integration automatically handles language locale differences between the two services. This language mapping applies both to source and target languages of your linked Transifex project. In cases where more than two similar locales are available in your Transifex project, the most common locale is selected. For example, if your Zendesk Help Center supports German (de), and the linked Transifex project has both de and de_DE as target locales, the Zendesk content will be linked with the de locale in Transifex.
The automatic mapping applied follows the supported locales for Zendesk Help Center and the locales that Transifex supports. You can find a complete list of the supported language mapping in Transifex to Zendesk locales language mapping.
Through the Zendesk integration, you have the option to provide a different translation for identical source strings that are included in the same article. For example, if your Zendesk article contains the following strings:
<p> Whether you are translating a website, mobile or desktop app, even subtitles, Transifex gives you all the tools and power you need to manage your localization process. </p> <p> A continuous process that I could completely leave on autopilot. </p> <p class="u-color-dark o-heading-small u-marBottom-x4 u-fontWeight-light"> Thousands of leading tech companies speak to new markets by using Transifex. </p> <p class="u-fontWeight-thin u-color-gray u-marBottom-x4"> Give Transifex a try with our free 15 day trial, or connect with one of our team members for a personal demo. </p> <p class="u-color-dark o-heading-small u-marBottom-x4 u-fontWeight-light"> A continuous process that I could completely leave on autopilot. </p>
once this article is synced with your Transifex project, all the above strings will be available for translation in Transifex Web Editor. The identical strings can easily be found in the editor using the "repeated_strings:yes" filter.
The key for the first string, as shown above is "A continuous process that I could completely leave on autopilot." while the key for the second string is "A continuous process that I could completely leave on autopilot._1". These keys are automatically generated by Transifex that way so that repeated strings can be handled as different entries in the editor.
Once the translations are completed in Transifex, the corresponding article in Zendesk will be updated accordingly.
If you are using the previous version of the Zendesk integration you can easily migrate to the new version by following the instructions to “Authenticate Zendesk to your Transifex organization” and “Linking a specific Transifex project with Zendesk content” for the Transifex project you have already linked with Zendesk using the previous Zendesk Integration.
All your translations and localization status will remain intact by this action. We took extra care to make sure that the workflow of all the Transifex - Zendesk integration is not affected.
Finally, you will have to remove the previous integration from your Zendesk account by:
- Visiting your My Apps page in the Zendesk admin interface, find the Transifex app.
- Click the options menu on the Transifex app and then select Uninstall.
- In the Uninstall App window, click Uninstall App.
It is recommended to switch to the new version of the integration as the previous one will not be maintained and gradually, totally deprecated.
The main reason for building the new integration with Zendesk was to offer a better experience and improved performance when syncing content between the two services, affecting integrations and syncing on a big number of articles and dynamic content.