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.
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
- 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.
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.
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.
- 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.
- GlobalLink Connect
- Lingotek Inside Zendesk
- Translate Media
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.
- 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.
The list of translation services is not updated and some of these companies are no longer working.
I would appreciate a recommendation for a company that can help in localize helpdesk to Hebrew
Thanks for bringing this to our attention! I will pass this feedback along to our documentation team to see if we can get this list updated.
Thank you, I have updated the article accordingly.
If you are still look for someone to do Hebrew translations, I can see that Translate Media can do this for you.
I hope you find this helpful.
How do you manage identifying articles that have been translated in some languages but are missing others?
Hey CJ! I'm late to the game on this question but Guide Admin will let you filter for articles that are not translated to your elected languages. Under the filter menu, select Not translated to and select a language.
Madison Hoffman Unfortunately, this seems to ignore the status of the articles. I know there's articles published in other languages, that are not published in English. The system returns 0 articles not translated to English, because I guess an unpublished draft technically exists?
This makes sense to me, and I would deem this to be expected behavior, especially when paired with the logic of the 'Language' filter. I'm unable to come up with a feasible workaround. Your comment did generate a ticket, which I've marked as product feedback. I would also welcome you to share this feedback in our Community.
Has anyone else had the issue of orphan articles due to manual translations? My team operations and offers help in English and Spanish.
We have all Categories (and 1 section per category) in Spanish and English. However by default, when you "add translation" to an article, the "category/section" is in the original language.
When I write an article in English, appropriately categorize it, and then translate it into Spanish, the Spanish article is put in an English category (and thus is not visible as Zendesk doesn't show a Spanish article in an English category). When I go in to just edit the Spanish one and change the Category to the Spanish Category... it says "this will affect all translations" -- and then it moves the English article to Spanish, rendering it orphan.
This makes absolutely no sense to me, as the point of a translation is to live in a separate different language category/section.
The behavior you are currently experiencing is expected when it comes to how translations are stored. Translations are not designed to be accessed separately on the Help Center on the same locale. However, it will be visible to users depending on the language of the Help Center they are in. You don't have to move them manually to a different category/section but you need designate the translation of the same categories and section that they are currently in.
I have made a sample using English AU and English US. My default language is English US and created a translation, English AU. If ever that translation does not have a translated category and section it will give you this message.
What you need to do is designate the correct translation for the categories and section so that depending on the language your end-users are using they will still see the article once they switched locale/language.
The best demonstration for this behavior is with this actual article above. If you change from en-us to pt-br, you'll eventually be presented with the corresponding translated article.
Is there a way to easily duplicate all content from, say, German Germany (de-de) into Austrian German (de-at)?
Our Help Center supports multiple languages, but not all the articles are translated yet. What is the best practice for modifying the URL address of referenced articles, within an article? Should we always remove the '/en-us' in the URL address, OR will Zendesk automatically display the article based on the user's selected language?
Yes, just remove the locale string (e.g. "/en-us") from the URL, and your help center will detect the user's browser setting and display the translated article if available -- see In what language do my help center articles display to my customers?
A similar question to Josine above: our guide is available in English as well as 4 other languages — localization is handled through Crowdin. When building the pages, we used the native linking tool in the article builder to link to other pages in the guide. However, the links on the localized pages are still en-us and so a user navigating a page in French, for example, will get bumped to the English version.
Besides manually updating every single link to remove en-us, is there another way to ensure the links correctly map in their localized instances, i.e. so a user in the French instance will be able to navigate between pages in French?
I am interested in the answer to Jen Hutton's question; we are handling our translations through Lingpad and would like to know what would be the correct process before we start pushing all the content from Lingpad to the Guide.
It will entirely depend on how these apps create articles in Zendesk.
Our help center API have the capability to designate locales for each article that will be created. This way, you will not have to manually designate the translations. Unfortunately, it should also be utilized by the apps you are using to work. It's also an option to manually utilize these APIs for the articles to be designated on their corresponding locales.
I was in a session where the Zendesk team explained that for translations, they have an approach of a mix of human translations and machine translations. How do you decide which articles should be done by real translators and which articles could be done by AI?
Hi Rebeca! Our audience predominantly uses our content in English and English is our source language, so we look at utilization of our content in English to try and understand which is being used most often. We typically follow the Pareto Principle that 80% of our traffic tends to be focused on 20% of our content, so we focus our human translation efforts/budget on the top 20% by pageviews in English. The bottom 80% are machine translated. In addition, even the top 20% of our articles go through a machine translation process first so that a human is only cleaning up or editing the output. This helps control our translation costs.
Hi Madison Hoffman thank you very much for the detailed explanation. This helps a lot.
In the manual workflow, it says:
However, in the first two approaches (Zendesk integration and help center API), I couldn't find any info on how these workflows handle updates to existing guides.
If you use a translation integration or the help center API, how do you handle updates to existing guides?
We have been trying to find a better way to handle translations of published articles with "in progress" status (currently, we're using a manual workflow for this type of request, which is not optimal).
In our team, "In-progress" articles are sent for translation only after our writers finish updating the source content of an existing article, but the updated content has not been pushed live yet.
We have in place the Zendesk connector for Smartling, which works well for new articles but can't handle the in-progress use case. Are we missing something? What would be a possible solution to handle this use case?
Please sign in to leave a comment.