Translations

Translations represent the content in all supported languages of a Help Center item such as an article or a section. The default language is also included in the translations.

JSON Format

Translations have the following keys:

Name Type Read-only Mandatory Comment
id integer yes no Automatically assigned when a translation is created
url string yes no The API url of the translation
html_url string yes no The url of the translation in Help Center
source_id integer yes no The id of the item that has this translation
source_type string yes no The type of the item that has this translation. Can be Article, Section, or Category
locale string no yes The locale of the translation
title string no yes The title of the translation
body string no no The body of the translation. Empty by default
outdated boolean no no True if the translation is outdated; false otherwise. False by default
draft boolean no no True if the translation is a draft; false otherwise. False by default
created_at timestamp yes no The time at which the translation was created
updated_at timestamp yes no The time at which the translation was last updated
updated_by_id integer yes no The id of the user who last updated the translation
created_by_id integer yes no The id of the user who created the translation
Example
{
  "id":          3243452,
  "source_id":   768934,
  "source_type": "Article",
  ...
}

List Translations

  • GET /api/v2/help_center/articles/{article_id}/translations.json
  • GET /api/v2/help_center/sections/{section_id}/translations.json
  • GET /api/v2/help_center/categories/{category_id}/translations.json

Lists all translations for a given article, section, or category.

Allowed for
  • Agents
  • End users

For end users, the response will list only the translations for articles, sections, or categories that they can view in Help Center.

Filter Parameters

You can filter translations by using one or more of the following filter parameters:

Name Type Example Meaning
locales list of locales locales=en-us,en-uk Only return translations in the given locales
outdated boolean outdated=true Only return translations with the given outdated status
draft boolean draft=true Only return translations with the given draft status
Using curl
curl https://{subdomain}.zendesk.com/api/v2/help_center/articles/{id}/translations.json?outdated=true \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "translations": [
    {
      "id":          634578,
      "source_id":   348756,
      "source_type": "Article",
      "locale":      "en-us",
      "outdated":    true,
      ...
    },
    ...
  ]
}

List Missing Translations

  • GET /api/v2/help_center/articles/{article_id}/translations/missing.json
  • GET /api/v2/help_center/sections/{section_id}/translations/missing.json
  • GET /api/v2/help_center/categories/{category_id}/translations/missing.json

Lists the locales that don't have a translation for a given article, section, or category.

Allowed for
  • Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/help_center/articles/{article_id}/translations/missing.json \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "locales": ["en-us", "da-dk"]
}

Show Translation

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

Allowed for
  • Agents
  • End-users
Using curl
curl https://{subdomain}.zendesk.com/api/v2/help_center/articles/{article_id}/translations/{locale}.json \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "translation": {
    "id":          634578,
    "source_id":   348756,
    "source_type": "Article",
    "locale":      "en-us",
    "title":       "How to take pictures in low light",
    ...
  }
}

Create Translation

  • POST /api/v2/help_center/articles/{article_id}/translations.json
  • POST /api/v2/help_center/sections/{section_id}/translations.json
  • POST /api/v2/help_center/categories/{category_id}/translations.json

Creates a translation for a given article, section, or category. Any locale that you specify must be enabled for the current Help Center. The locale must also be different from that of any existing translation associated with the source object.

Allowed for
  • Help Center Managers
  • Agents (article translations only)

The requesting agent can create an article translation only if they can edit the article in Help Center.

Using curl
curl https://{subdomain}.zendesk.com/api/v2/help_center/articles/{article_id}/translations.json \
  -d '{"translation": {"locale": "en-us", "title": "Super Hero Tricks", "body": "This article contains a collection of Super Hero tricks"}}' \
  -v -u {email_address}:{password} -X POST -H "Content-Type: application/json"
Example Response
Status: 201 Created
Location: https://{subdomain}.zendesk.com/api/v2/help_center/translations/{id}.json

{
  "translation": {
    "id":     37486578,
    "locale": "en-us",
    ...
  }
}

Update Translation

  • PUT /api/v2/help_center/articles/{article_id}/translations/{locale}.json
  • PUT /api/v2/help_center/sections/{section_id}/translations/{locale}.json
  • PUT /api/v2/help_center/categories/{category_id}/translations/{locale}.json

When updating a translation, any locale that you specify must be enabled for the current Help Center. If you change the translation locale, it must be different from that of any existing translation associated with the same source object.

Allowed for
  • Agents (only articles)
Using curl
curl https://{subdomain}.zendesk.com/api/v2/help_center/articles/{article_id}/translations/{locale}.json \
  -d '{"translation": {"title": "How to use HDR"}}' \
  -v -u {email_address}:{password} -X PUT -H "Content-Type: application/json"
Example Response
Status: 200 OK

{
  "translation": {
    "id":    37486578,
    "title": "How to use HDR?",
    ...
  }
}

Delete Translation

DELETE /api/v2/help_center/translations/{id}.json

Deletes a translation, provided it's not the only translation for the source object.

Allowed for
  • Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/help_center/translations/{id}.json \
  -v -u {email_address}:{password} -X DELETE
Example Response
Status: 204 No Content

List all enabled locales and default locale

GET /api/v2/help_center/locales.json

Allowed for
  • Agents
  • End-users
Example response
Status 200 OK

{
  "locales": ["de-de", "en-uk", "en-us", "es-419", "es-es", "fr-fr", "it-it", "ja-jp", "pt-br"],
  "default_locale": "it-it"
}