Monthly Archives: February 2016

Localize Zendesk Help Center, and Make PDFs Too

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.

image (1)

 

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.

Watching My Doggie Die

Aji Keshi passed away today. He had lymphoma, which often gets Golden Doodles, but it was tragic he died so young, at six and a half. He was loving and gentle, the perfect big beast of a dog.

It was hard to watch him get sicker, and then choose exactly the moment to let go. As I sit writing this, it’s not that hard though – watching him pass was endless tears, and knowing he’s gone is a touch of melancholy.

So many thoughts pass your head as your dog dies – guilty thoughts, sad thoughts, reflective thoughts. You think about how this is hard, but it would be unbearable with real, human family. You think maybe you should have walked the dog more, maybe you should have gotten a mutt. Mostly you think what a great dog he is though, and how sad it is, and it’s a lot of tears across weeks or months to watch your dog die of cancer.

So Aji Keshi is gone today, but his sister-in-spirit Tenuki lives on with us. I think Adlai will ask about Aji in a day or two, but he won’t really feel his passing, and that’s for the best – Adlai can learn of this pain some other time.

The vet cried with us as Aji passed, she’s a trooper. Such a hard job.

DSC_0034