Automating your first localization handoff (Help Center)

This article describes how to use the Zendesk REST API to package the content of your Help Center so you can hand it off to a localization vendor for translation for the first time. You'll also learn how to automate the reverse process: publishing the translated content on Help Center after it comes back from the translators.

The article assumes you haven't localized any of your content yet and are starting from scratch. Support for multiple languages is available on the Plus and Enterprise plans of Zendesk Support.

The article is based on custom automation scripts the docs team at Zendesk uses to localize the Zendesk Support documentation.

The article walks you through the following tasks:

• Part 1: Developing a localization workflow
• Part 2: Setting up your scripting environment
• Part 3: Creating the initial handoff package
• Part 4: Publishing the translated content

Disclaimer: Zendesk provides this article for instructional purposes only. Zendesk does not support or guarantee the code. Zendesk also can't provide support for third-party technologies such as Python. Please post any issue in the comments section or search for a solution online.

Part 1: Developing a localization workflow

Before doing anything else, settle on a workflow for localizing your content. The Zendesk docs team uses the following basic workflow for getting content localized:

1. On handoff day, we download the HTML of the English articles and write them to HTML files.

2. We bundle the HTML files with our image files in a zip file, and then hand off the package to the localization vendor.

3. After the vendor returns the translated HTML files, we upload the translated HTML to the knowledge base.

4. Finally, we upload new or updated images to an offsite file server we use to host our images.

Most of our content is generated from DITA source files stored in Box and sync'ed to the writers' laptops. However, we use the Web content as our master for translation because it always has our most up-to-date content.

What's included in the handoff package

The initial handoff package described in this article consists of the following folders:

/handoff
    /current
    /graphics
    /README.pdf

The current folder contains the most up-to-date English HTML files.

The graphics folders contain the English source image files for the articles.

The readme file contains information for the translators. The document covers the following topics:

• Description of the folders containing the text and image files
• Any extra strings to localize not captured in the HTML files, such as category and section titles
• Any other notes, such as how to handle titles or cross-references

Managing images

The images in most articles in the Zendesk documentation are hosted on an Amazon S3 file server. This option provides more flexility for managing images. You can add, update, or delete the images on the file server using a file client such as Cyberduck.

A file server also gives you more flexibility in terms of managing the images in localized articles. You can create and populate folders of localized images on the file server with a simple suffix to differentiate the languages. Example:

• user_guide
• user_guide_de
• user_guide_fr
• user_guide_ja

Then, in the localized articles, you can switch to the localized version of an image by changing the HTML src attribute. For example, if the src attribute of an English image is as follows:

src="http://cdn.oscura.com/images/documentation/user_guide/visit_icon.png"

then adding the "de" suffix to "userguide" displays the German version of the image:

src="http://cdn.oscura.com/images/documentation/user_guide_de/visit_icon.png"

You can make this change for all the images in all the German files with a simple global search and replace of "_guide/" with "_guide_de/".

Setting up your scripting environment

This article uses Python to help automate the localization process. Python is a powerful but beginner-friendly scripting and programming language with a clear and readable syntax. Visit the Python website to learn more.

All you need to write and run Python scripts is a text editor and a command-line interface like Terminal on the Mac or the command prompt in Windows. You'll need a few more tools to develop your localizaton scripts. This section describes how to get them.

Topics covered:

• Install Python
• Install Requests
• Install Beautiful Soup

If you're interested in taking a deeper dive into Python after finishing this article, see the following free resources:

• Dive into Python 3 by Mark Pilgrim
• Think Python by Allen B. Downey

Install Python

The scripts in this article use version 3 of Python.

To install Python

• Go to http://www.python.org/download/ and install the latest stable production version of Python 3 for your operating system.

You can test the installation by running python3 --version on the command line. It should give you the Python version number.

Install Requests

The Requests module is a third-party Python library that simplifies making HTTP requests in Python. To learn more, see Requests: HTTP for Humans.

To install the Requests module

• At the command line, enter:

  $ pip3 install requests
  

  That's it. The command downloads and installs the latest version of the module.

Note: If you have Python 3.3 or earlier, you need to install pip separately. See the instructions on the pip website. Once installed, use pip instead of pip3 on the command line.

Install Beautiful Soup

Beautiful Soup is a Python library that provides tools for parsing, navigating, searching, and modifying HTML trees. The scripts in this article rely on the module to parse and modify the Help Center's HTML articles. To learn more, see the Beautiful Soup website.

To install the Beautiful Soup module

1. At the command line, enter:

   $ pip3 install beautifulsoup4
   

   The command downloads and installs the latest version of the module.

2. Install lxml, an HTML parser that works with Beautiful Soup:

   $ pip3 install lxml
   

   Beautiful Soup works with a number of parsers; lxml is one of the fastest.

Part 3: Creating the initial handoff package

In this part, you build a script that uses the Zendesk REST API to download the articles in your knowledge base and create an HTML file for each article. After running the script, you'll be able to hand off your content to a localization vendor for a cost estimate and translation.

The script assumes the content you want to hand off is contained in one category on your Help Center.

Script spec

Here are the basic tasks the script has to accomplish to create the handoff package:

• Download the HTML of the articles from the Help Center.
• Because the title of each article is not included in the article's HTML body, get the title from the API and insert it as an h1 tag in the article's HTML.
• Write an HTML file for each article.

Set up the folder structure

Create the following folder structure to store the handoff files and your scripts:

/production
    /handoff
        /current
        /graphics
    /scripts

Create the script

Save the script below as create_package.py in the scripts folder.

Important: When using the scripts in this article, make sure to indent lines as shown. Indentation matters in Python.

The script downloads the default-language "translation" of the articles from Help Center and writes them to HTML files in the handoff/current folder. The sections that follow describe how to change the settings and run the script, and how it works.

import os

import requests
from bs4 import BeautifulSoup

subdomain = 'your_subdomain'                # setting
email = 'your_email'                        # setting
password = 'your_zd_password'               # setting
session = requests.Session()
session.auth = (email, password)
session.headers = {'Content-Type': 'application/json'}

locale = 'en-us'                           # setting

sections = ['36406', '200122006']                # setting
# ignore = ['23650177', '33992907', '44356063']  # setting
ignore = []

file_path = os.path.join('..', 'handoff', 'current')

for section in sections:
    articles = []
    url = 'https://{}.zendesk.com/api/v2/help_center/sections/{}/articles.json'.format(subdomain, section)
    response = session.get(url)
    if response.status_code != 200:
        print('Failed to get articles in section {}. Error {}.'.format(section, response.status_code))
        exit()
    print('\nSuccessfully retrieved the articles in section {}:'.format(section))
    data = response.json()
    [articles.append(article['id']) for article in data['articles']]

    for article in articles:
        if str(article) in ignore: continue
        url = 'https://{}.zendesk.com/api/v2/help_center/articles/{}/translations/{}.json'.format(subdomain, article, locale)
        response = session.get(url)
        data = response.json()
        if 'error' in data:
            continue

        tree = BeautifulSoup(data['translation']['body'], 'lxml')
        meta = tree.new_tag('meta')
        meta['charset'] = 'utf-8'
        head = tree.new_tag('head')
        head.append(meta)
        h1 = tree.new_tag('h1')
        h1.string = data['translation']['title']
        tree.body.insert_before(h1)
        tree.h1.insert_before(head)

        filename = '{}.html'.format(article)
        with open(os.path.join(file_path, filename), mode='w', encoding='utf-8') as f:
            f.write('<!DOCTYPE html>\n' + tree.prettify())
        print('- Saved {}'.format(filename))

Change the settings

1. Replace the values for subdomain, email, and password:

   subdomain = 'your_subdomain'
   email = 'your_email'
   password = 'your_zd_password'
   

   For example, if your Zendesk Support URL is obscura.zendesk.com, then use 'obscura' as the value of your Zendesk Support subdomain:

   subdomain = 'obscura'
   

   The email and password are the same as the ones you use to sign in to Zendesk Support. You must be a Zendesk Support admin or agent with access to the content. To be safe in case your laptop is lost or stolen, enter the password value only when you run the script and then delete it when you're done.

2. Specify the locale of your default language:

   locale = 'en-us'
   

   You can get the valid locale value by looking at the URL of your Help Center in your default language:

   https://obscura.zendesk.com/hc/en-us

   You can also get a list of valid locales for your Zendesk Support account with the following curl request:

   curl https://{subdomain}.zendesk.com/api/v2/locales.json \
   -v -u {email_address}:{password}
   

3. Use the sections and ignore variables to specify the content you want to include in the handoff:

   sections = ['21535856', '21825876', '33838271']
   ignore = ['23650177', '24919921', '33992907', '44356063']
   

   Use the sections variable to list all the sections to include in the handoff. If a section is not listed, the script ignores it. You can use the setting to skip sections that don't need to be translated, such as agent-only sections.

   Use the ignore variable to list all the articles within the included sections that you don't want to include in the handoff.

   If you don't want to ignore any articles, use the following statement:

   ignore = []
   

4. Save the file.

Run the script

1. Navigate to your scripts folder with your command line interface.

2. Run the script from the command line as follows:

   $ python3 create_package.py
   

   Note: The dollar sign ($) represents the command prompt. Don't enter it.

   You should get messages confirming that the articles were retrieved and saved to HTML files.

3. Check your handoff/current folder to confirm that it contains the new files. The folder should contain all the articles in the sections you listed, minus the articles you listed to ignore.

4. Open a few files in a text editor to confirm they contain the HTML for the articles. Check to make sure the title was inserted as an h1 tag.

How it works

The script performs the following tasks.

Import libraries and define variables

1. Import the libraries used in the script:

   import os
   import requests
   from bs4 import BeautifulSoup
   

   The os library is a native Python library that lets you work with files and file paths. You installed the other two libraries.

2. Specify the parameters for making requests to the Zendesk API:

   subdomain = 'your_subdomain'
   email = 'your_email'
   password = 'your_zd_password'
   session = requests.Session()
   session.auth = (email, password)
   session.headers = {'Content-Type': 'application/json'}
   

   The requests module is used to create a session object and set the authentication and headers for your HTTP requests.

3. Specify the locale of your default language:

   locale = 'en-us'
   

4. Specify the section content to include in the handoff:

   sections = ['21535856', '21825876', '33838271']
   ignore = ['23650177', '24919921', '33992907', '44356063']
   

5. Specify where to write the HTML files:

   file_path = os.path.join('..', 'handoff', 'current')
   

   The location is expressed as a path relative to folder where the script runs -- in this case, your scripts folder. The path is ../handoff/current/.

   The os.path.join() function ensures the path is valid regardless of your OS. For example, in Windows, it expresses the path as ..\handoff\current\.

Fetch the article ids

The script needs to article ids to get the content of the articles.

1. Create a loop to iterate through each section in your sections list and create a list variable to store the article ids:

   for section in sections:
       articles = []
   

   On each iteration, you'll retrieve the ids of all the articles in the section.

2. Define the url to use for the API request:

   url = 'https://{}.zendesk.com/api/v2/help_center/sections/{}/articles.json'.format(subdomain, section)
   

   The url changes dynamically with each iteration. The format() string method inserts (or interpolates) the values of its arguments in the placeholders ({}) in the string.

   The url points to the list articles endpoint, which is defined in the API docs as follows:

   GET /api/v2/help_center/sections/{id}/articles.json

   where {id} is the section id. The endpoint fetches the metadata, including article ids, for all the articles in the specified section. Because you want to get articles from several sections, the script makes one request for each section in your sections list. The url will be different for each request. The section variable that's interpolated in the url provides a different {id} value for each iteration of the loop.

   Using the example values, on the first iteration the value of url is as follows:

   https://your_subdomain.zendesk.com/api/v2/help_center/sections/21535856/articles.json
   

3. Make the request and save the response:

   response = session.get(url)
   

   This simple statement makes a GET request to the API using the authentication and header parameters defined earlier. It fetches the metadata for all the articles in the section and assigns it to the response variable. For an example of the response, see the API doc.

4. Check for request for errors and report back:

   if response.status_code != 200:
       print('Failed to get articles in section {}. Error {}.'.format(section, response.status_code))
       exit()
   print('Successfully retrieved the articles in section {}:'.format(section))
   

   According to the API doc, the API returns a status code of 200 if the request was successful. In other words, if the status code is anything other than 200 (if response.status_code != 200:), then something went wrong. The script prints an error message and exits.

   If the script didn't exit, it means a status code of 200 was returned and the script prints a success message.

Access the article ids in the response

At this point, the metadata for all the section's articles is contained in the response variable as JSON data. The script needs to decode the data and store the id of each article so that it can fetch the contents of the articles from the translations API.

1. Decode and assign the response to a new variable:

   data = response.json()
   

   The json() function decodes the data returned by the API into a Python dictionary, which is a built-in data type. A dictionary is simply a set of key/value pairs formatted almost identically to JSON. Example dictionary:

   {'id': 35436, 'author_id': 88887, 'draft': true }
   

   Consult the Zendesk API docs to figure out how the data dictionary is structured. For example, according to the articles API doc, the JSON returned by the API has the following structure:

   

   You can deduce from the doc that the Python dictionary consists of one key named 'articles'. Its value is a list of articles, as indicated by the square brackets. Each item in the list is a dictionary of article properties, as indicated by the curly braces.

2. Create a list of article ids from the data:

   [articles.append(article['id']) for article in data['articles']]
   

   This is a Python list comprehension, a concise way of looping through a data collection to create a list. It's equivalent to the following snippet:

   articles = []
   for article in data['articles']:
       articles.append(article['id'])
   

   The for loop iterates through each article in the data['articles'] list, gets the value of the article id, and appends it to the articles list.

3. Create a loop to iterate through the list of article ids:

   for article in articles:
   

   You want to loop through each article in the current forum to retrieve the article's content from the translations API.

4. Check to see if the current article id is on your ignore list:

   if str(article) in ignore: continue
   

   If the article id (converted to a string to avoid a data-type mismatch) is on the ignore list, the script skips the rest of the loop and gets the next article in the articles list.

   If the article is not on the ignore list, the script fetches its content and writes it to a file, as described in the next sections.

Fetch the content of the article

In the Help Center API, the metadata and the content of an article are provided by different resources. You get the metadata from the articles API. You get the content from the translations API, which also includes the default-language content.

1. Define the url to use for the API request:

   url = 'https://{}.zendesk.com/api/v2/help_center/articles/{}/translations/{}.json'.format(subdomain, article, locale)
   

   The url points to the get translations endpoint, which is defined in the API docs as follows:

   GET /api/v2/help_center/articles/{article_id}/translations/{locale}.json

   The endpoint gets the content of the specified article for the specified locale.

   In the url string, a different article value is interpolated at the second placeholder in the string on each iteration of the articles loop. The locale value is interpolated in the string at the third placeholder and doesn't change. Its value is defined at the top of the script, in this case en-us.

2. Make the request, decode it, and save the response:

   response = session.get(url)
   data = response.json()
   

Parse and modify the HTML

Before writing the article to a file, the script needs to get the title of the article from the data variable and insert it in the article's HTML as an h1 tag. Otherwise the translators won't know the title of the article.

The script should also add a meta tag that specifies a UTF-8 character set. Some browsers and localization tools might default to a different encoding without it.

The script manipulates the HTML using the Beautiful Soup library, which provides tools for parsing, navigating, searching, and modifying HTML trees.

1. Start by creating the Beautiful Soup tree (also known as making the soup) with the article body:

   tree = BeautifulSoup(data['translation']['body'], 'lxml')
   

   The article body is specified by the body property of the translation object in the API response.

2. Create a <meta> tag and set its charset attribute to "utf-8" for browsers and localization tools:

   meta = tree.new_tag('meta')
   meta['charset'] = 'utf-8'
   

   The lines create the following HTML tag:

   <meta charset="utf-8"/>
   

3. Create a <head> tag and insert your <meta> tag in it

   head = tree.new_tag('head')
   head.append(meta)
   

   The lines create the following tag structure:

   <head>
     <meta charset="utf-8"/>
   </head>
   

4. Create a <h1> heading tag with the article title:

   h1 = tree.new_tag('h1')
   h1.string = data['translation']['title']
   

   The article title is specified by the title property of the translation object in the API response. The lines create the following HTML tag:

   <h1>Some article title</h1>
   

5. Insert the <h1> tag before the <body> tag, and the <head> tag before <h1>:

   tree.body.insert_before(h1)
   tree.h1.insert_before(head)
   

Write the article to a file

The modified HTML in the Beautiful Soup tree is ready to be written to a file for the translators.

1. Specify a unique filename based on the article id:

   filename = '{}.html'.format(article)
   

   The name is based on the article id to ensure there are no duplicates. Example: 24919921.html

2. Write the article to a new file:

   with open(os.path.join(file_path, filename), mode='w', encoding='utf-8') as f:
       f.write('<!DOCTYPE html>\n' + tree.prettify())
   

   The snippet creates a new file in write mode (mode='w') and writes the contents of the HTML tree to it.

   The value of file_path is specified at the top of the script and points to your handoff/current folder. The script creates the files in this folder.

   The prettify() function converts a Beautiful Soup tree into a nicely formatted string with each HTML tag on its own line. A DOCTYPE tag is prepended to the HTML.

3. Print the results:

   print('- Saved {}'.format(filename))
   

Prepare the readme file and hand off the package

You're ready to hand off the HTML files to a localization vendor for a cost estimate and translation.

Before you do, make sure to write a readme file that includes any extra strings that need to be localized. For the initial handoff, this includes the name of your Help Center, the title of the documentation category, and the titles of all the sections included in your handoff.

Note: After the files have been handed off, don't delete the **current** folder and all its files. You'll need them in your next localization handoff to identify new files in the handoff package.

Part 4: Publishing the translated content

After a while, you get the translated content back from the localization vendor. The vendor should have returned translated versions of the articles, as well as the names of your Help Center, documentation category, and sections. This part describes how to publish the content in your Help Center.

Uploading translations of articles to Help Center is a fairly straightforward operation using the API. The problem is making sure categories and sections exist for each supported language before uploading the articles, especially on your first localization pass when they don't exist yet.

Any translated page must have a parent page translated in the same language. The page hierarchy is as follows: Category > Section > Article. For example, if you add an article translated in German, the article must be contained in a German section. The German section must in turn be contained in a German category. You can't upload an orphan article. For more information on the page hierarchy, see Anatomy of the Help Center.

When localizing your Help Center, it makes sense to start by adding localized versions of category landing pages, followed by section landing pages, followed by articles. This workflow guarantees that any new translated article has a section and category in the same language.

Topics covered in this section:

• Enable your supported languages
• Add the category translations
• Add the section translations
• Add the article translations
• Updating the article translations

Enable your supported languages

Before you begin, make sure you defined the languages in your Zendesk Support account. For instructions, see Selecting the languages you want to support.

After defining the languages for your account, enable them for Help Center as follows.

1. In Help Center, click General Settings in the tools panel on the lower-right side of the page.

   

2. On the General Settings page, select the languages you want to enable for Help Center.

   

3. Enter the localized Help Center name for each of your languages.

4. Click Update to save your changes.

Add category translations

Because you're only localizing one category, it's easier to add a category translation with the user interface rather than with the API.

To add translations of your category

1. After signing in as a Help Center manager, navigate to the category containing your docs.

2. Click Edit category in the tools panel on the lower-right side of the page.

3. Click to add a translation of the category from the list on the right side of the page:

   

4. Enter the translated name for the category.

   (You did include the category name in the strings in your readme file to the localization vendor, right?)

5. Click Update Translation to save your changes.

6. Repeat for each supported language.

Add the section translations

This article assumes you included more than a handful of sections in your handoff package, so it uses the API to add section translations. The script is designed to read the translated titles from a csv file, so a little preparatory work is necessary.

Add the translated titles to a csv file

1. Create a csv (Comma Separated Values) file named translated_titles.csv in the scripts folder.

2. In a text editor, enter the following information on each line:

   section_id,"title for first locale","title for second locale",...

   The section ids should be the same ids specified in the sections variable in the create_package.py file. They're the sections you included in the handoff package.

   Example for a Help Center being localized in German and French:

   42453453,"Erste Schritte","Mise en route"
   42535344,"Konfigurieren des E-Mail-Kanals","Configuration du canal des emails"
   53434522,"Business-Regeln","Règles de gestion"
   

Rules:

• Add a row for each section you included in the handoff package
• Don't include a heading row
• Add a column for each translated version of a section title
• Make sure the title columns are in alphabetical order by locale. Example: de, fr, ja.
• Make sure there's no space before or after the commas that separate the columns
• Use double quotes for the titles in case they contain commas

Create the script

Save the script below as add_section_translations.py in the scripts folder.

This script creates language-specific translations for each section included in your handoff package. It assumes you created a csv file as described in the previous topic. The topics that follow describe how to change the settings and run the script, and how it works.

import csv
import json
import requests

subdomain = 'your_subdomain'                # setting
email = 'your_email'                        # setting
password = 'your_zd_password'               # setting
session = requests.Session()
session.auth = (email, password)
session.headers = {'Content-Type': 'application/json'}

locales = ['de', 'fr']                     # setting

with open('translated_titles.csv', encoding='utf-8', newline='') as f:
    title_reader = csv.reader(f, delimiter=',')

    sections = {}
    for row in title_reader:
        titles = {}
        count = 1
        for locale in locales:
            titles[locale] = row[count]
            count += 1
        sections[row[0]] = titles

for section in sections:
    url = 'https://{}.zendesk.com/api/v2/help_center/sections/{}/translations.json'.format(subdomain, section)
    for locale in locales:
        data = {'translation': {'locale': locale, 'title': sections[section][locale]}}
        payload = json.dumps(data)
        response = session.post(url, data=payload)
        print("Translation for locale '{}' created for section {}.".format(locale, section))

Change the settings

1. Replace the values for subdomain, email, and password.

   You must be a Zendesk Support admin or agent with access to the content. Enter the password value only when you run the script and then delete it when you're done.

2. For the locales variable, add or remove the locales for your supported languages. The locales should be the same as they appear in the URLs of your Help Center.

   locales = ['de', 'fr']
   

3. Save the file.

Run the script

1. Run the script from your command-line interface:

   $ python3 add_section_translations.py
   

   You should get a message confirming that translations were created for the sections.

2. Check the section in your Help Center to see if it contains the new translations.

   Because the sections don't contain any articles yet, they're not visible to end-users, signed-in or otherwise. The sections are visible to agents and administrators.

How it works

1. Import the required libraries:

   import csv
   import json
   import requests
   

   Python has built-in support for csv files.

2. Configure the request parameters:

   subdomain = 'your_subdomain'
   email = 'your_email'
   password = 'your_zd_password'
   session = requests.Session()
   session.auth = (email, password)
   session.headers = {'Content-Type': 'application/json'}
   

3. Specify the locales of your translated articles.

   locales = ['de', 'fr']
   

4. Read the csv file:

   with open('translated_titles.csv', encoding='utf-8', newline='') as f:
       title_reader = csv.reader(f, delimiter=',')
   

5. Store the translated section titles in a Python dictionary:

   sections = {}
   for row in title_reader:
       titles = {}
       count = 1
       for locale in locales:
           titles[locale] = row[count]
           count += 1
       sections[row[0]] = titles
   

   The first loop creates a dictionary of sections, with the section id as the key of each item. The locales loop creates a dictionary of translated titles for each section. The titles dictionary is assigned as the value of each section key (sections[row[0]] = titles). The resulting value of sections might look like this:

   {
       '42453453': {'de': 'Erste Schritte', 'fr': 'Mise en route'},
       '42535344': {'de': 'Konfigurieren des E-Mail-Kanals', 'fr': 'Configuration du canal des emails'},
       '53434522': {'de': 'Business-Regeln', 'fr': 'Règles de gestion'}
   }
   

   The titles have their own locale-specific keys to select them later.

6. For each section, add a section translation using the creating translation endpoint:

   for section in sections:
       url = 'https://{}.zendesk.com/api/v2/help_center/sections/{}/translations.json'.format(subdomain, section)
   

7. For each locale, retrieve the section title from the sections dictionary, build the API payload, and make the post request:

   for locale in locales:
       data = {'translation': {'locale': locale, 'title': sections[section][locale]}}
       payload = json.dumps(data)
       response = session.post(url, data=payload)
       print("Translation for locale '{}' created for section {}.".format(locale, section))
   

   Each new translation is defined in the API payload as follows:

   data = {'translation': {'locale': locale, 'title': sections[section][locale]}}
   

   The script defines the locale and title for each section translation. The title comes from the sections dictionary created from the csv file:

   sections[section][locale]
   

   The expression identifies a value in the dictionary. The section and locale variables change as the script iterates through the loop. Using the example dictionary above, sections[53434522]['de'] resolves to the value of 'Business-Regeln'.

   Note that because the new language-specific sections don't contain any articles yet, end-users won't be able to see them. Only admins and agents can see them at this point.

Add the article translations

The final step in the workflow is to add the article translations to Help Center.

Get the article files ready

1. Create folders for the translated files.

   Create the following locale-specific folders in the handoff folder on your hard drive:

   /handoff
       /current
       /localized
           /de
           /fr
   /script
   

   Make sure the structure is identical relative to the scripts folder.

   Add or remove the locale-specific folders for your supported languages. The locale folder names should be the same as the locales in the URL of Help Center.

2. Place the HTML files for each language in the appropriate locale-specific folder.

   Make sure the HTML files from the vendor have the same file names as the default-language files. Example:

   /handoff
       /current
           22521706.html
           27808948.html
       /localized
           /de
               22521706.html
               27808948.html
           /fr
               22521706.html
               27808948.html
   

3. Upload the localized image files to your image file server.

   On the server, you should organize the images in locale-specific folders. Example:

   /documentation
       /user_guide (existing folder with English images)
       /user_guide_de
       /user_guide_fr
   

   You can use a file client such as Cyberduck to upload the images.

4. Change the image paths in the localized HTML files to point to the language-specific folder on the file server.

   For example, if an image src attribute in a German article is as follows:

   src="http://cdn.oscura.com/images/documentation/user_guide/visit_icon.png"
   

   then add the "_de" suffix to "user_guide" to display the German image:

   src="http://cdn.oscura.com/images/documentation/user_guide_de/visit_icon.png"
   

   You can make this change for all the articles in your localized/de folder with a global search-and-replace of "_guide/" with "_guide_de/". Repeat for all your languages. For more information, see Managing images

Create the script

Save the script below as publish_package.py in the scripts folder.

The script publishes the translated articles to the appropriate language-specific sections in Help Center. The topics that follow describe how to change the settings and run the script, and how it works.

Change the settings

1. Replace the values for subdomain, email, and password.

   You must be a Zendesk Support admin or agent with access to the content. Enter the password value only when you run the script and then delete it when you're done.

2. For the locales variable, add or remove the locales for your supported languages. The locales should be the same as they appear in the URLs of your Help Center.

Run the script

1. Run the script from your command-line interface:

   $ python3 publish_package.py
   

   You should get messages confirming that each translation was created in Help Center.

2. Check your Help Center to see if it contains the new article translations in your language-specific categories and sections.

How it works

The script performs the following basic tasks:

• Read each file in each locale folder.
• Because the title of each article on Help Center is not included in the HTML body, grab the article title in the h1 tag in the HTML, and then delete the h1 tag.
• Create an article translation in Help Center with the translated HTML content.

Here are the details.

1. Import the required libraries.

   import os
   import glob
   import json
   
   import requests
   from bs4 import BeautifulSoup, Comment
   

2. Define a function named main().

   def main():
   

   Unlike the previous scripts, this one defines a few custom functions. The main() function is defined here but called on the last line of the script to make sure Python reads the other function definitions first.

3. Configure the request parameters.

   You should be familiar with these lines by now.

4. Specify the locales of the supported languages:

   locales = ['de', 'fr']
   

5. For each locale, grab, or glob, the names of all the HTML files in the ../handoff/localized/{locale} folder:

   for locale in locales:
       print('Processing {} articles ...\n'.format(locale))
       files = glob.glob(os.path.join('..', 'handoff', 'localized', locale, '*.html'))
   

   The glob.glob() function in Python scrapes the contents of a specified folder. In this case, the function gets the names of all the html files ('*.html') in the locale folder. The resulting value of files is a list that looks like ['../handoff/localized/fr/22521706.html', '../handoff/localized/fr/27808948.html'].

6. Define a variable to use later to slice off the file path to obtain the article id contained in the file name:

   path_len = 22 + len(locale)
   

   The value of file is a relative path and a file name. The path_len variable specifies the length of the relative path (always the same 22 characters), plus the length of the locale, which can vary. Examples, 'fr', 'en-gb'.

7. Start a loop to read the translated content in each file in the folder:

   for file in files:
       print('Reading {} ...'.format(file[path_len:]))
   

   The status message uses the Python slice expression, file[path_len:], to print the name of the file. If the current locale is 'de', the expression slices the first 24 characters (22 + 2) from the beginning of the file string. For example, if the string is '../handoff/localized/fr/22521706.html', then the expression produces '22521706.html'.

8. For each file, create a JSON payload containing the file's translated content:

   payload = create_payload(locale, file)
   

   The create_payload() function is defined in the Functions section later in the script. It parses the translated HTML in the file, retrieves the article title from the h1 tag in the HTML, strips out the h1 tag, strips out any HTML comments for good measure, packages the HTML in a dictionary, and returns it as a JSON-encoded payload for the API request:

   def create_payload(locale, file):
       with open(file, mode='r', encoding='utf-8') as f:
           html_source = f.read()
   
       tree = BeautifulSoup(html_source, 'lxml')
       title = tree.h1.string.strip()
       tree.h1.decompose()
   
       # Strip out html comments
       comments = tree.find_all(text=lambda text: isinstance(text, Comment))
       for comment in comments:
           comment.extract()
   
       # Package the payload in a dict and JSON-encode it
       data = {'translation': {'locale': locale, 'title': title, 'body': str(tree)}}
       return json.dumps(data)
   

9. Use the JSON payload in an API request to create the article translation in Help Center:

   url = 'https://{}.zendesk.com/api/v2/help_center/articles/{}/translations.json'.format(subdomain, file[path_len:-5])
   post_translation(payload, url, session)
   

   The script uses the following endpoint to create the article translations:

   POST /api/v2/help_center/articles/{id}/translations.json

   where {id} is the id of the article to update. The script gets the id from the file variable:

   file[24:-5]
   

   The second number, -5, slices five characters starting from the end of the string, which removes the '.html' extension and leaves the article id.

   The post_translation() custom function makes the request and checks for problems:

   def post_translation(payload, url, session):
       response = session.post(url, data=payload)
       if response.status_code != 201:
           print('Status:', response.status_code, 'Problem with the post request. Exiting.')
           exit()
       print('Translation created successfully.')
   

10. Print the URL of the newly updated article:

    print('https://{}.zendesk.com/hc/{}/articles/{}.html\n'.format(subdomain, locale, file[path_len:-5]))
    

The localized content is live. Help Center shows or hides the content in the sections based on the language setting of the end-user’s browser, or based on the language selector on Help Center pages.

Update the article translations

You might need to fix errors in the translated content and republish it. Make the edits in the locale folders in your localized folder and then run the script described below. The script updates the translated articles to the appropriate language-specific sections in Help Center. The topics that follow it describe how to change the settings and run the script, and how it works.

Save the script as update_package.py in the scripts folder.

Change the settings

1. Replace the values for subdomain, email, and password.

   You must be a Zendesk Support admin or agent with access to the content. Enter the password value only when you run the script and then delete it when you're done.

2. For the locales variable, add or remove the locales for your supported languages. The locales should be the same as they appear in the URLs of your Help Center.

Run the script

1. Run the script from your command-line interface:

   $ python3 update_package.py
   

   You should get messages confirming that each translation was updated in Help Center.

2. Check your Help Center to see if it contains the updated article translations in your language-specific categories and sections.

How it works

The script works like the create_package.py script, except that it uses a different endpoint and makes a PUT request instead of a POST request. See Updating translations in the API docs. If you're interested, see "How in works" in Add the article translations above.