We needed to internationalize the user documentation for Gaia GPS recently, so I wrote some open source scripts that automate Zendesk+Gengo localization. I found this to be a delightful task as a programmer – it was a finite problem, with a clear cut solution, and I could just kind of code away and see it come to life without many issues.
These scripts (in Python) let you select a chunk of your Zendesk Help Center, post the articles to Gengo for translation, retrieve the translations, and post the localized articles back to Zendesk.
When I started working on this, I found the blog post that Zendesk wrote about using their API for localization. That code was a big help, but it produces static files to hand off to a localization firm. I wanted my scripts to do a bit more:
- totally automate the round trip between Zendesk and Gengo – i.e. script gives English to Gengo, and script posts locales back to Zendesk
- allow us to localize a chunk of our voluminous Help Center, and later a different chunk with just some configuration
- estimate the cost of the localization that was about to be requested
PDFs Too
The main reason I did this project was to better localize Gaia GPS for international users, but I also wanted to generate nice PDFs of the help docs, to cache in the app for users to read while offline. For example, here’s the Gaia GPS Help Center, converted to PDF, in Russian. It also generates an inventory of the PDFs too.
This script now runs as a cron job for Gaia GPS, so the PDF manual gets updated each night. This is a good hack to give our users an offline version of the user manual, both in the app, and also for printing (surprisingly common request). Hopefully Zendesk will make their SDK (cough, ahem, closed source, or I’d fix it myself) work offline someday, but the PDFs will do until then.
Localization Usage
You can follow along the docs on Github, but the gist is this:
- edit project_settings.py
- add your Zendesk/Gengo credentials
- configure which categories, sections, or articles to translate
- run the script in Gengo’s sandbox
- make sure the articles and cost are what you expect
- the Python script estimates the Gengo cost, but you can double check in the sandbox too
- run the script in production
- run the package and post steps
- wait for Gengo translators to do their work
- run the retrieve and update steps
PDF Usage
See the PDFing docs on Github, but again, the gist is:
- edit project_settings.py
- beyond what you configured for localization, add info about an S3 bucket to post the manuals to if you want to use the “post” command
- add your own custom name, logo, and background image.
- run the script with “create” and again with “post”
- create – generate PDFS for all languages locally – one for each language/category pair
- post – puts the PDFs on S3
- if you use the default “User Manual” title provided, the script will localize the title automatically, using the included data
Aside: Make a Business Out of These Scripts
As I wrote these scripts, it occurred to me that companies would pay hundreds or thousands of dollars to use a simple web interface that wrapped these scripts.
I don’t think this is a billion dollar idea, but I think a good hustling programmer could make a few hundred thousand dollars or a few million even making Gengo↔Zendesk automatic and easy for non-programmers. If Gaia GPS wasn’t keeping me so busy, I might give it a whirl, but anyone who comes across this code is welcome to try.
Semi-related: Transfer a Uservoice Knowledge Base to a Zendesk Help Center
We found that UserVoice didn’t have a capability to localize our Knowledge Base, so that’s why we moved to Zendesk (though, p.s., we also now like a lot of other things about ZenDesk).
So, this code also includes a Python script to transfer your Uservoice KB to a Zendesk HC, if you find yourself in similar need.