Answered

Can I use the Articles API to translate my articles?

  • 8 January 2021
  • 2 replies
  • 177 views

Userlevel 2
Badge

I have a Help Center full of articles in one language and want to programatically translate them into other languages. Can I use Intercom's API to do this?

icon

Best answer by Daniel F11 8 January 2021, 11:12

View original

2 replies

Yes, absolutely! 😎

 

I recently localized an English help centre into pt-BR (Brazilian Portuguese) using Python and Intercom Articles API.

 

Requirements 

 

- It is assumed that you already have an access token to retrieve and post data into your Intercom account (check from the Intercom Developer Hub)

- It is assumed that you can create a localized version of your help centre (upgrade your Intercom subscription if necessary)

- It is assumed that you have the latest version of Python and Python requests library in your machine together with some application to run code (ex: Visual Studio Code or similar)

 

Step-by-step

 

- Extract a JSON file from the Articles API containing all English articles

 

import requests

 

articles_url = 'https://api.intercom.io/articles#39;

headers = {'Authorization' : '[ACCESS TOKEN]', 'Accept': 'application/json','content-type': 'application/json'}

articles_list = []

 

def get_data(articles_url):

  

  articles_response = requests.get(articles_url, headers=headers)

  articles_output = articles_response.json()

  pagination_data = articles_output['pages']

  articles_data = articles_output['data']

 

  for item in articles_data:

    if item['state'] == 'published':

      articles_list.append(item)

 

  if pagination_data.get('next'):

    get_data(pagination_data['next'])

 

get_data(articles_url)

 

with open('intercom_articles.json','w') as outfile:

  json.dump(articles_list, outfile)

 

- Share the output with your in-house translator or translator agency so they can send you back the localized content as a JSON file as well (make sure that translations keep the original article IDs for reference purposes)

 

The output should be formatted as a list of dictionaries where each item is a separate article, for example: 

 

[

  {

   "id":"4466498",

   "type":"article",

   "workspace_id":"[YOUR WORKSPACE_ID]",

   "title":"Keyboard Shortcuts",

   "description":"How to save time using keyboard shortcuts",

   "body":"<p class=\"no-margin\">Are you a Klaus pro already?</p>\n<p class=\"no-margin\">Then you can save even more time by using our keyboard shortcuts.</p>\n<p class=\"no-margin\"></p>\n<p class=\"no-margin\">You can access the list of shortcuts by clicking on the question mark in the black toolbar on the left.</p>\n<p class=\"no-margin\"></p>\n<p class=\"no-margin\">Shortcuts for Mac:</p>\n<p class=\"no-margin\"></p>\n<p class=\"no-margin\"></p>\n<div class=\"intercom-container\"><img src=\"https://downloads.intercomcdn.com/i/o/248106542/453f1f746fac34b175a7e4cf/image.png\quot;></div><p class=\"no-margin\"></p>\n<p class=\"no-margin\">Shortcuts for Windows:</p>\n<p class=\"no-margin\"></p>\n<p class=\"no-margin\"></p>\n<div class=\"intercom-container\"><img src=\"https://downloads.intercomcdn.com/i/o/248126234/aad06ba48be5dbe11a764887/image.png\quot;></div><p class=\"no-margin\"></p>\n<p class=\"no-margin\">If you have any other possible shortcuts to suggest, please <a href=\"https://support.klausapp.com/en/articles/3666496-how-can-i-contact-klaus\quot; target=\"_blank\">get in touch!</a></p>",

   "author_id":3565392,

   "state":"published",

   "created_at":1600697577,

   "updated_at":1600700522,

   "url":"http://support.klausapp.com/en/articles/4466498-keyboard-shortcutsquot;,

   "parent_id":2128132,

   "parent_type":"collection",

   "statistics":{

     "type":"article_statistics",

     "views":8,

     "conversations":0,

     "reactions":0,

     "happy_reaction_percentage":0,

     "neutral_reaction_percentage":0,

     "sad_reaction_percentage":0

   }

  },

...

]

 

The translations should be formatted as a list of dictionaries where each item is a separate article translation, for example:  

 

[

  {

   "id":"4466498",

   "type":"article",

   "workspace_id":"[YOUR WORKSPACE_ID]",

   "title":"Atalhos do teclado",

   "description":"Como economizar tempo usando os atalhos do teclado",

   "body":"<p class=\"no-margin\">Você já domina o funcionamento do Klaus?</p>\n<p class=\"no-margin\">Então, poderá poupar ainda mais tempo usando nossos atalhos do teclado.</p>\n<p class=\"no-margin\"></p>\n<p class=\"no-margin\">Acesse a lista de atalhos clicando no ponto de interrogação na barra de ferramentas preta à esquerda.</p>\n<p class=\"no-margin\"></p>\n<p class=\"no-margin\">Atalhos para Mac:</p>\n<p class=\"no-margin\"></p>\n<p class=\"no-margin\"></p>\n<div class=\"intercom-container\"><img src=\"https://downloads.intercomcdn.com/i/o/248106542/453f1f746fac34b175a7e4cf/image.png\quot;/></div><p class=\"no-margin\"></p>\n<p class=\"no-margin\">Atalhos para Windows:</p>\n<p class=\"no-margin\"></p>\n<p class=\"no-margin\"></p>\n<div class=\"intercom-container\"><img src=\"https://downloads.intercomcdn.com/i/o/248126234/aad06ba48be5dbe11a764887/image.png\quot;/></div><p class=\"no-margin\"></p>\n<p class=\"no-margin\">Se você quiser sugerir outras opções de atalhos, <a href=\"https://support.klausapp.com/en/articles/3666496-how-can-i-contact-klaus\quot; target=\"_blank\">fale conosco!</a></p>",

   "author_id":3565392,

   "state":"published",

   "created_at":1600697577,

   "updated_at":1600700522,

   "url":"http://support.klausapp.com/en/articles/4466498-keyboard-shortcutsquot;,

   "parent_id":2128132,

   "parent_type":"collection",

   "statistics":{

     "type":"article_statistics",

     "views":8,

     "conversations":0,

     "reactions":0,

     "happy_reaction_percentage":0,

     "neutral_reaction_percentage":0,

     "sad_reaction_percentage":0

   }

  },

...

]

 

- Create a pt-BR version of the help centre in your Intercom Articles settings page and then loop over all original English articles to inject their respective pt-BR translations in draft mode (so you can review them before publishing to users)

 

articles_url = 'https://api.intercom.io/articles#39;

headers = {'Authorization' : '[ACCESS TOKEN]', 'Accept': 'application/json','content-type': 'application/json'}

 

with open('intercom_pt_articles.json') as json_file:

  pt_translations = json.load(json_file)

 

for article in pt_translations:

  single_article_url = articles_url + "/" + article['id']

  translation_content = {'translated_content': {'pt-BR': {'type': 'article_content', 'title': article['title'], 'description': article['description'], 'body': article['body'], 'state': 'draft'}}}

  try:

    inject_translation = requests.put(url=single_article_url, headers=headers, json=translation_content)

    print(inject_translation.status_code)

  except requests.exceptions.HTTPerror as error:

    raise SystemExit(error)

 

Notes

 

This process ensures that translations are correctly associated with their originals and landing in the appropriate collections and sections (if any) inside the Intercom database. It does not translate collection and section names which need to be manually translated. 

 

You check the final result here: https://support.klausapp.com/pt-BR//p>

Badge

Hi @Inter C12 

 

Here’s an additional tip: If you have multilingual articles in CSV or another help desk platform, you can import them to Intercom using Help Desk Migration.

This automated migration tool supports transferring articles, folders, categories, and inline images to Intercom. You can also request customizations, such as updating cross-links in articles or migrating only articles with a "Published" or "Draft" status.

You can migrate to a specific workspace or merge multiple Intercom workspaces.

Run a free demo to see how Help Desk Migration transfers 20 random articles to Intercom, or try a demo with custom data to import specific article IDs.

For a fully custom migration tailored to your business needs, run a free demo first, then contact the support team to discuss the details.

Reply