Zendesk

Take advantage of our Zendesk integration to synchronize Help Center content and finished translations between Zendesk and Transifex.

T
Written by Transifex
Updated over a week ago

With the Zendesk integration, you can synchronize your Help Center content and finished translations between Zendesk and Transifex. Allow your localization team to leverage Transifex's powerful tools and effortlessly translate your Help Center articles.

📝Note:

  • The integration is available on the Starter plan and up.

  • You’ll need to be on Zendesk’s Suite Growth plan or Enterprise, as only those plans support multilingual content.

  • Integrating Transifex with Zendesk will enable all your Transifex project maintainers to sync content between Zendesk and their projects in Transifex.

🚨Compatibility with Zendesk Integration 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 further. It is highly recommended to switch to the new integration. Read more on switching to the new integration here.


Setting up the Zendesk Integration

The following video will show you a step-by-step process for connecting, authorizing, and configuring the Zendesk Integration. Additionally, you will learn how to configure your Zendesk Help Center to support multiple languages. We have also included the same instructions below so you can reference them.

Connecting Zendesk to your Transifex Organization

To connect your Zendesk and Transifex accounts, you need to be a Transifex administrator.

When creating the project, be sure to:

  1. Visit your Transifex Organization Settings.

  2. From the Left-hand Side Menu that appears, select Integrations.

  3. Enter your main Zendesk subdomain in the respective input box and press Authorize.

    Connecting your main Zendesk subdomain provides access to all available Zendesk subdomains and brands in your Zendesk account.

  4. You will be redirected to Zendesk to authorize the integration with Transifex.

    Allow access to Zendesk

Authorizing integration with Transifex and getting back to Organization settings > Integrations, you will see the respective Zendesk integration box as active. This means the integration is ready to use, and you can start syncing content between Transifex and Zendesk.

Configuring your Zendesk help center to support multiple languages

By default, your Zendesk Help Center only supports one language. You have to configure it to support additional languages. You must do this in The Zendesk Admin Center and the Help Center Settings.

1. Admin Center

  1. From your Admin Center home, click on the Account icon.

  2. Click on the Localization tab or use the search function to find it.

  3. Set your default language from the dropdown. This should be the same as the source language you set for your project in Transifex.

  4. Click Additional Languages and select the languages you want to support in your Help Center. They should match the target languages you chose when you created your project earlier.

  5. Lastly, click Save.

2. Help Center

Next, we’ll repeat the same setup inside the Help Center:

  1. From the top menu bar of the Admin Center, click on the windows/grid icon on the top right and click on Guide.

  2. Click on Guide admin in the top menu bar.

  3. Click the Gear icon on the left to go to your Language Settings.

  4. Click on the Language settings option from the tab on the left. Click on Add new language and select the same set of languages as before.

  5. Hit Save at the top of the page to save your settings.


Linking a specific Transifex project with Zendesk content

In the video below, you will learn how to connect specific Transifex Projects with Zendesk and sync content between Zendesk and Transifex.

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 wizard's first step, 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 here, please follow the instructions on Configuring your Zendesk Help Center to support multiple languages.

When you finish 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 can view content per content type supported and search across Articles and Dynamic Content leveraging various criteria, such as title, categories, sections, status, etc. When you identify Zendesk content you want to sync to your Transifex project, mark it by checking the box on the left of the title. Any selections 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 of this wizard’s step by checking the respective section to Choose content for translation below.

When you are done 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 content back to Zendesk happens automatically based on the following triggers:

  • Content is 100% translated, reviewed, or proofread.

  • Content is updated when a language is already 100% translated, reviewed, or proofread.

In addition, you can choose the state in which translated articles will be pushed back to Zendesk: either as published or as a draft. By default, translations are published immediately.

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. Just so you know, this option can only be set during the initial setup of the integration, so you won't be able to change it later.

When you finish this setup step, click the Update Settings & Synchronize button to start syncing content from Zendesk to Transifex.

Some steps described above are also accessible when updating the integration settings. Check Editing the Transifex Project - Zendesk content link section below for more.

📝Note: All Zendesk content 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.

If the option is unchecked, we always ignore translations found on Zendesk and never send them to Transifex.

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 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 one 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 integration setup or new content detected on a subsequent sync. Any syncing actions on content with a resource in Transifex will not include translations updated on Zendesk. Check Syncing content localized in Zendesk to Transifex for more details.

Choose content for translation

In this subsection, we are expanding on the full functionality provided in the content selection step of the wizard.

In this step, you will find information about Zendesk content on the subdomain you linked to the specific Transifex project. More specifically, you will see a list of either:

  • Articles

  • Dynamic content

  • Categories

  • Sections

When content is selected, a ribbon appears at the top of the list informing of 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.

  • It will appear as checked if the content is selected to sync between Zendesk and Transifex. Otherwise, it will appear unchecked.

  • If an article in Zendesk is published, a green dot will appear before the title.

    • If, on the other hand, the article is in a draft state, the dot becomes gray.

    • Categories, sections, and dynamic content do not have a status indication.

  • In the case of articles, you can see under which category and section each article belongs.

  • There is a link to the Transifex resource hosting translations of content with an icon at the end of the row:

    image16.png#asset:8151

  • If the content in Zendesk is in a draft state, the title of the content will have a badge like this:

  • The "Updated at" field holds the date of the last update of the content or the content metadata in Zendesk.

  • Finally, there is a link to the Transifex resource hosting translations of content. It appears when a resource in Transifex corresponds to the same Zendesk content. The icon appears at the end of the row:

Filtering and sorting content

To filter the content displayed in the list, you can choose among the following criteria:

  • The content type (articles, categories, sections, dynamic content).

    • Default: content type is “articles”.

  • A part of or the whole title

  • Content or content metadata updated before/after

  • Single selection of a category

  • Single selection of a section

  • Multiple selections of a label

  • The status (published, draft)

The content list can be filtered by pressing the Enter key or Search button based on the selected criteria.

💡Tip: You can use double quotes around the search terms to make searching more focused.

To clear out a search term, delete it and press the Enter key or Search button; alternatively, you can use the X icon in the search area.

You can also sort the search results by the Updated at field or the title, either ascending or descending.

Items in the list have pagination. You can change the page size using the dropdown displayed under the content list and navigate through the different pages using the left and right arrows located in the same area under the content list.

In case you don’t see in the list the latest Zendesk content (the timestamp of which is shown under the list), even after filtering/sorting, you can click on the Refresh Content button to get the latest data from Zendesk. The search criteria are applied on top of the refresh functionality.

Brands support

The synchronization wizard allows linking the current project in Transifex with a brand (subdomain) in Zendesk. This can be done in the wizard's first step when creating the integration in the project settings.

The brands allowed to be selected have an active Help Center in Zendesk. If you'd like 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 integration setup 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.

String segmentation on Dynamic content

If you use 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.

image21.png#asset:8155

Here is an example to showcase the result of the segmentation: In a case of dynamic content that contains five sentences, with the segmentation enabled, five strings will be added in the source language resource versus a single source string when the segmentation is disabled. When 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 those 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.

Pushing localized content options

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:

  • When the content is 100% translated.

  • When the content is 100% reviewed.

  • When the content is 100% proofread.

Depending on the setting selection, this will apply to individual content entries as they are localized in each target language.​

For example, once an article is fully translated into 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.​


The sync options for 100% translated/reviewed/proofread are triggered when the language reaches 100% completion and when there are updates to the translations that have already been completed, reviewed, or proofread. This ensures that any edits to the translations of an already reviewed language will be automatically sent to Zendesk.

Furthermore, you can control how the translated articles will be pushed to Zendesk. If you want the translated articles to be published immediately, check the option “Push translated articles as published”. If you leave this option unchecked, the translated articles will be saved in Zendesk as drafts.

Use Cases

  • If your localized article is already published, whether manually or through previous configuration, the "Push translations as published" setting is disabled, and new translation edits are detected in Transifex, then the most recent translations will be automatically fetched. As a result, the corresponding Zendesk localized article will be set as a draft in Zendesk for your review.

    The localized article will not be accessible by your end users until the latest translation edits are approved, and the article is published again. It's important to note that this change only affects the specific article and does not impact the rest of your articles.

  • If your source article is in draft mode and you have enabled the "Push translations as published" setting, any completed localized articles sent from Transifex to Zendesk will be automatically set as published.

📝Note: Translated content synced back to Zendesk can be available in your Help Center in a few minutes (approximately 3 minutes) up to a few hours (about 4 hours). This depends on the size of your content and is related to how Zendesk renders the Help Center, which is outside the scope of the integration.


Translating content in Transifex

All content synced from Zendesk to Transifex will create a resource following the Zendesk content name. For example, suppose you have two articles in Zendesk titled “Getting Started” and “Quick Installation”, syncing them to Transifex via the integration. In that case, you will get two resources with the same names, “Getting Started” and “Quick Installation”.

The Zendesk content type is passed as a resource category in Transifex, visible on the resources page. Especially for Zendesk articles, the integration migrates the Zendesk category and section as resource categories.

Once your content is inside Transifex, you have several translation options:


Syncing content from Zendesk to Transifex

The synchronization of content from Zendesk to Transifex can occur either through manual actions by selecting the desired articles and clicking "Save & Synchronize" or automatically on an hourly basis. When a syncing process is initiated, you will be able to see that syncing is in progress in your Project settings > Integrations tab inside the Zendesk card. This process could take some time, depending on the number and size of the files that are being synced.

image11.png#asset:8157

The integration automatically detects updated source content on Zendesk, provided you have selected “Auto-pull new articles” or “Auto-pull updated articles” for articles you've selected to sync with Transifex. Updates on other types of Zendesk content, e.g., categories, sections, etc., are not automatically fetched from Zendesk.

📝Note: If translations exist for new articles in Zendesk, these will not be transferred to Transifex, even if the option "Fetch initial translations from Zendesk" is enabled.

If you want to force a sync from Zendesk to Transifex, you can use the Update Settings & Synchronize button.

Suppose you want to re-sync existing contents from Zendesk to the respective resources in Transifex. In that case, you should click Edit Settings in the project integration to show the Integration Wizard, then push the Update Settings & Synchronize button to start a new sync process.

If you want to add new content for synchronization, repeat the same process described previously, but before pushing the Update Settings & Synchronize button, check all the new content you want to sync.

📝Note: The Zendesk integration works on top of the HTML, which is quite an unstructured file format. When syncing translations from Zendesk to Transifex, please keep in mind their structure and order differences, as it might affect the mapping of translations to the proper strings.

If you would like more details, please check Managing HTML translation files.


Manual sync

There is an option to manually send localized content to Zendesk without waiting for a resource to be 100% translated or reviewed. A Send to Zendesk option is available on the Projects settings > Integrations tab in the Zendesk card.

image19.png#asset:8158

By clicking Send to Zendesk, a modal will appear requesting the threshold localization percentage that Transifex will check on all your project's resources.

image9.png#asset:8159

All target languages that are localized above that threshold will be synced with Zendesk using the Sync content options you have set up for the integration. For example, suppose you had set up Zendesk to Sync 100% translated resources. In that case, the manual process will identify all target languages whose translation percentage is equal to or above the threshold percentage you set on the modal and sync all content back to Zendesk.

📝Note: 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. This issue will be eliminated when that content is fully translated on Transifex and synced back to Zendesk.


Syncing status report

To check the most recent synchronization results, whether from Transifex to Zendesk or from Zendesk to Transifex, there is a popup that displays relevant information for each process and the syncing status report dialogue.

image19.png#asset:8158

To view this modal, head 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 find the Transifex to Zendesk or Zendesk to Transifex sync activity, along with the date of the most recent sync. The modal displays the last five syncs (or fewer if there have been fewer than five since the integration was installed) for each direction.

If a syncing direction does not have a syncing status yet or there are no translations to sync back to Zendesk, an explanatory message will be displayed on the right side, informing you that there is nothing to report.

Expanding each syncing direction, you will be able to see:

  • A list of all synced resources along with each resource’s type, language (source or target, depending on the direction), the sync status (“Success” or “Error”), and the date the sync occurred.

  • A detailed error message as a tooltip in case one or more resources fail to sync in either direction.

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.

Finally, in case an article is not accessible in Zendesk anymore, an error message will be displayed in the sync report, similar to the example shown below, when attempting to send its translations back to Zendesk. The system will treat the specific source article as missing.

Although the article will still be listed in the wizard (reflecting the last synced snapshot) when you open it again, it will no longer appear in the list of articles for translation once you save the sync settings and manually trigger a sync with Zendesk. To make the article available again in the wizard for syncing, you will need to manually save the configuration after fetching the latest content from Zendesk.


Editing the Transifex Project - Zendesk content link

As your Help Center evolves, you can either extend the Zendesk content you are syncing to Transifex or change the workflow of pushing localized content back to Zendesk. If you'd like to edit your options, you can 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.

⚠️Warning: If you deselect already synced Zendesk content, the associated resource(s) will no longer be synced with Zendesk. Also, the associated resource in Transifex will not be deleted.

You can learn more about all the different options in the Filtering and sorting content section of our Choose content for translation article.


Handling language mapping between Zendesk and Transifex

The integration automatically handles language locale differences between the two services. This language mapping applies to the 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 follows the supported locales for Zendesk Help Center and the ones that Transifex supports. You can find a complete list of the supported language mapping in Transifex to Zendesk locales language mapping.


Duplicate strings in Zendesk Articles

Through the Zendesk integration, you can provide a different translation for identical source strings 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.&nbsp;
</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.


Compatibility with Zendesk 1.0

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 ensure the workflow of all the Transifex - Zendesk integration is unaffected.

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.

Switching to the new version of the integration is recommended, as the previous one will not be maintained and will gradually become 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 many articles and dynamic content.

📝Note: The Zendesk API has certain limitations if content blocks have been enabled for one or more articles. One of them is when updating an article or translation. Specifically, the body property of the Update Article and Update Translation endpoints does not support content blocks.


💡Tip

Looking for more help? Get support from our Transifex Community Forum!

Find answers or post to get help from Transifex Support and our Community.

Did this answer your question?