Creating and managing translated content for your Zendesk Guide knowledge base

Available on all Guide plans Available on all Suite plans

Note: Guide customers who are not on a Suite plan must have Support Professional or Enterprise with any Guide plan to support multiple languages.

You can provide your customers with a completely localized (translated), user experience. This includes all the words in the user interface as well as your knowledge base content.

Zendesk automatically provides localization of the user interface and also the means to host and present your translated articles. You can also display custom snippets of translated text on your help center pages. For example, you may want to add a welcome message on the home page or a company tagline in the header.

In this article, we explain how you might set up and manage the authoring, translation, publishing, and updating of your knowledge base content.

Note: Managing translated content in your business rules and support ticket workflow is handled by a feature in the Admin Center called dynamic content.

If you haven't already done so, you need to first enable multiple language support and then build out the structure of your localized versions of Zendesk Guide, as described in Localizing help center content.

This article covers the following topics:

Authoring and managing your knowledge base content in Zendesk Guide
Your options for managing content translation
Use Zendesk translation integrations provided by third party translation services
Use the help center API to automate the managing, handoff, and publishing of your content
- How the Zendesk Documentation team creates and manages content and handles translations
- Other examples of using the help center API to integrate with a translation service
Managing your translations manually

Authoring and managing your knowledge base content in Zendesk Guide

Zendesk Guide includes an easy to use editor and content management tools to create knowledge base articles directly in Zendesk Guide. When you choose other languages to support, you can easily create language-specific versions of your articles — Guide creates the container for you, but you must provide the translated content to insert into them. See Localizing help center content.

You can author your articles directly in Guide using the editor and you can also view and edit the underlying HTML source of those articles. See Editing the source code of help center articles.

For many Zendesk customers, the editor and content tools available in Guide are sufficient for creating and managing knowledge base articles. However, when you decide to start supporting other languages, your choice of a translation provider and the processes that come with that choice may affect what tools you’ll use to author and manage your knowledge base content.

The biggest challenges involved with managing translated content is getting the content to and back from the translation service provider, publishing the content, and then keeping it up to date — and, do all that with as little manual work as possible.

With those challenges in mind, let’s look at your options for managing your knowledge base content and translations.

Your options for managing content translation

As you saw in the previous section, in Zendesk Guide you can easily create the containers for additional language versions of your articles. However, unless you have a staff of in-house translators, you need to find an external resource to do the translations. That means finding a way to get your default language content to and back from those external translators.

Here are your options — in order of recommended approach.

Find a translation service that provides a Zendesk integration. As you can see below in Use Zendesk translation integrations provided by third party translation services, there are many translation services that are integrated with Zendesk and make the exchange of content and its ongoing management a fairly easy and automated process. We highly recommend that you consider this approach for your help center translations.
Create your own integration and translation handoff process using the help center API. The means by which the translation agencies are able to integrate with Zendesk are available to you to create your own homegrown automated translation tools. The Zendesk Documentation team uses an implementation of the help center API to process our translations, and as you’ll see below in Use the help center API to automate the managing, handoff, and publishing of your content so do a number of Zendesk customers. This requires some programming, but there’s plenty of sample code available to get you started.
Use a manual process for managing and handing off content. This isn’t the ideal way to handle translations, but if you don’t have much content it may work for you. A number of Zendesk customers use this approach so we include it here as well, see Managing your translations manually below. This approach doesn't scale well, but may help you get started before you move to a better, more integrated solution.

In the following sections of this article we’ll describe each of the following options in more detail.

Use Zendesk translation integrations provided by third party translation services

Many cloud-based translation services are available to help you manage and translate your knowledge base content, working directly in Zendesk Guide. These are end-to-end solutions that do not require you to create any custom tools or do any programming with the help center API.

As an example, Unbabel, a Zendesk technology partner, has an integration called Unbabel Translate for Zendesk (available in the Zendesk Marketplace), that provides easy access to translation services for your customer service interactions and your knowledge base content.

Below is a list of many of the other translation services available that provide an integration with the Admin Center and Guide. A number of them are also available in the Zendesk Marketplace.

Note: This is for information purposes only. We have not used or tested any of these services and therefore do not endorse any of them. If you use or have used any of these services, feel free to share your experiences in the comments section of this article.

All of these services are separate from Zendesk and are an additional cost. You can refer to their websites for pricing information.

Use the help center API to automate the managing, handoff, and publishing of your content

You can use the Zendesk help center API to automate the management, handoff, and publishing of all your knowledge base content. This requires some programming skill to use the API for this purpose, but fortunately there are a number of implementations of this already available that you can start with.

How the Zendesk Documentation team creates and manages content and handles translations

The default language of our help centers is English. We translate the product documentation in German, Spanish, French, Japanese, and Brazilian Portuguese.

Although much of the content contained in Zendesk help centers is authored directly in Guide, the product documentation, which is always translated, is created by the technical writers on the Zendesk Documentation team. It’s authored in DITA (Document Information Typing Architecture), which is an XML-based data model for authoring and publishing.

The authoring tool we use to develop DITA content is Oxygen XML Author. It provides us with a robust technical documentation authoring experience and the flexibility to publish our content in many formats from a single source. Other authoring tools such as Framemaker, Arbortext, and XMetal (to mention just a few), can also be used to create DITA content.

From the English DITA source files, we output HTML, manually copy it in each article’s source code editor in Guide, and publish the articles.

When a localization handoff is due, we use the help center API to download selected English articles from the help centers as HTML files, then hand off the files to a translation agency. After the translators return translated versions of the HTML files, we use the API to automatically upload them to the help centers.

The API client we use to manage handoff files is called ZEP (Zendesk production tools), created by Charles Nadeau, one of the writers on the Docs team. ZEP is a collection of command-line tools for performing various help center production tasks. The client is open source and available on his Github page. You can read more about it in the ZEP documentation on Github.

You can think of the Zendesk Documentation team’s use of the help center API as a partially automated process because we manually bundle and hand off the files to our translation agency using a shared handoff folder. This is a process that we’ve been successfully using since 2012. However, the help center API can be used to completely automate the handoff and return of files for translations, as you’ll see next.

Other examples of using the help center API to integrate with a translation service

Zendesk customers GAIA GPS and Wire both used the help center API to integrate with a translation service and automate the round trip between their help center and their translation service providers.

GAIA GPS - Andrew L. Johnson from GAIA GPS used the help center API to integrate with Gengo, an online translation service. As he describes in Localize Zendesk help center, and Make PDFs Too, he built an integration to send “articles to Gengo for translation, retrieve the translations, and post the localized articles back to Zendesk”. His code is also available on Github.

Wire - Nick, a QA Specialist at Wire, describes how they used the help center API to create an integration with Crowdin, a localization management platform, which is similar to what GAIA GPS created. You can find the code for their project on Github.

Managing your translations manually

Many Zendesk customers start by authoring and maintaining their knowledge base content in Guide, and then when they start supporting other languages, find that they need to develop a manual process for handling their translations. This usually means using a spreadsheet and sending that file to their translation agency.

This is a manual process and involves the following steps.

Creating a spreadsheet with a column for each language you support
Moving your default language content into the spreadsheet
Handing that spreadsheet off to a translation agency
When the translation agency hands it back to you with your translated content, copying and pasting the translations into the language variation versions of the default language articles
Using the Guide editor to apply any formatting, if necessary
Publishing the translated versions of the articles, one at a time

Because the Guide editor allows you to access the underlying HTML of your articles, you may want to copy those source files into your spreadsheet and hand them off to the translation agency, especially if you’re using custom formatting and your own CSS.

With a manual approach like this, you also need a process for keeping track of changes that you make to your default language article content and then make sure that those changes are routinely sent to the translation agency to make sure that your language versions don’t get out of sync.

Within Guide, you can mark translated versions of articles as being out of date; therefore, needing an updated translation (see Marking a translated article as out of date).

As you can imagine, this approach is time consuming and becomes very difficult to manage when your knowledge base grows. This is why we recommend that you choose an integrated translation solution instead. If you’re already using a translation agency that doesn’t offer a Zendesk integration, the help center API is an excellent option for automating handoffs and managing your article translations.