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 are represented as JSON objects with the following properties:

Name	Type	Read-only	Mandatory	Description
body	string	false	false	HTML body of the translation. Empty by default
created_at	string	true	false	The time at which the translation was created
created_by_id	integer	true	false	The id of the user who created the translation
draft	boolean	false	false	True if the translation is a draft; false otherwise. False by default
html_url	string	true	false	The url of the translation in Help Center
id	integer	true	false	Automatically assigned when a translation is created
locale	string	false	true	The locale of the translation
outdated	boolean	false	false	True if the translation is outdated; false otherwise. False by default
source_id	integer	true	false	The id of the item that has this translation
source_type	string	true	false	The type of the item that has this translation. Can be "article", "section", or "category".
title	string	false	true	The title of the translation
updated_at	string	true	false	The time at which the translation was last updated
updated_by_id	integer	true	false	The id of the user who last updated the translation
url	string	true	false	The API url of the translation

Example

{
  "id": 3243452,
  "locale": "en",
  "source_id": 768934,
  "source_type": "Article",
  "title": "Hello translation"
}

List Translations

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

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

Allowed for

• End users

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

Pagination

• Cursor pagination (recommended)
• Offset pagination

See Pagination.

Parameters

Name	Type	In	Required	Description
draft	boolean	Query	false	Only return translations with the given draft status
locales	string	Query	false	The value given is a comma-separated list of locale names; only return translations in those locales
outdated	boolean	Query	false	Only return translations with the given outdated status
article_id	integer	Path	true	The unique ID of the article

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/v2/help_center/articles/{article_id}/translations.json?outdated=true \
  -v -u {email_address}:{password}

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://support.zendesk.com/api/v2/help_center/articles/360026053753/translations?draft=true&locales=en-us%2Cen-uk&outdated=true"
	method := "GET"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"

	client := &http.Client {}
	res, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer res.Body.Close()

	body, err := io.ReadAll(res.Body)
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(string(body))
}

Java

import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/v2/help_center/articles/360026053753/translations")
		.newBuilder()
		.addQueryParameter("draft", "true")
		.addQueryParameter("locales", "en-us,en-uk")
		.addQueryParameter("outdated", "true");

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("GET", null)
		.addHeader("Content-Type", "application/json")
		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'GET',
  url: 'https://support.zendesk.com/api/v2/help_center/articles/360026053753/translations',
  headers: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"
  },
  params: {
    'draft': 'true',
    'locales': 'en-us%2Cen-uk',
    'outdated': 'true',
  },
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Python

import requests

url = "https://support.zendesk.com/api/v2/help_center/articles/360026053753/translations?draft=true&locales=en-us%2Cen-uk&outdated=true"
headers = {
	"Content-Type": "application/json",
}

response = requests.request(
	"GET",
	url,
	auth=('<username>', '<password>'),
	headers=headers
)

print(response.text)

Ruby

require "net/http"
uri = URI("https://support.zendesk.com/api/v2/help_center/articles/360026053753/translations")
uri.query = URI.encode_www_form("draft": "true", "locales": "en-us,en-uk", "outdated": "true")
request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")
request.basic_auth "username", "password"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

Example response(s)

200 OK

// Status 200 OK

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

List Missing Translations

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

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

Allowed for

• Agents

Pagination

• Cursor pagination (recommended)
• Offset pagination

See Pagination.

Parameters

Name	Type	In	Required	Description
article_id	integer	Path	true	The unique ID of the article

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/v2/help_center/articles/{article_id}/translations/missing.json \
  -v -u {email_address}:{password}

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://support.zendesk.com/api/v2/help_center/articles/360026053753/translations/missing"
	method := "GET"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"

	client := &http.Client {}
	res, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer res.Body.Close()

	body, err := io.ReadAll(res.Body)
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(string(body))
}

Java

import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/v2/help_center/articles/360026053753/translations/missing")
		.newBuilder();

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("GET", null)
		.addHeader("Content-Type", "application/json")
		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'GET',
  url: 'https://support.zendesk.com/api/v2/help_center/articles/360026053753/translations/missing',
  headers: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"
  },
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Python

import requests

url = "https://support.zendesk.com/api/v2/help_center/articles/360026053753/translations/missing"
headers = {
	"Content-Type": "application/json",
}

response = requests.request(
	"GET",
	url,
	auth=('<username>', '<password>'),
	headers=headers
)

print(response.text)

Ruby

require "net/http"
uri = URI("https://support.zendesk.com/api/v2/help_center/articles/360026053753/translations/missing")
request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")
request.basic_auth "username", "password"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

Example response(s)

200 OK

// Status 200 OK

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

List Enabled Locales and Default Locale

• GET /api/v2/help_center/locales

Allowed for

• End users

Code Samples

curl

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

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://support.zendesk.com/api/v2/help_center/locales"
	method := "GET"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"

	client := &http.Client {}
	res, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer res.Body.Close()

	body, err := io.ReadAll(res.Body)
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(string(body))
}

Java

import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/v2/help_center/locales")
		.newBuilder();

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("GET", null)
		.addHeader("Content-Type", "application/json")
		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'GET',
  url: 'https://support.zendesk.com/api/v2/help_center/locales',
  headers: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"
  },
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Python

import requests

url = "https://support.zendesk.com/api/v2/help_center/locales"
headers = {
	"Content-Type": "application/json",
}

response = requests.request(
	"GET",
	url,
	auth=('<username>', '<password>'),
	headers=headers
)

print(response.text)

Ruby

require "net/http"
uri = URI("https://support.zendesk.com/api/v2/help_center/locales")
request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")
request.basic_auth "username", "password"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

Example response(s)

200 OK

// Status 200 OK

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

Show Translation

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

Allowed for

• End users

Parameters

Name	Type	In	Required	Description
article_id	integer	Path	true	The unique ID of the article
locale	string	Path	true	Mandatory locale parameter

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/v2/help_center/articles/{article_id}/translations/{locale}.json \
  -v -u {email_address}:{password}

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://support.zendesk.com/api/v2/help_center/articles/360026053753/translations/en-us"
	method := "GET"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"

	client := &http.Client {}
	res, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer res.Body.Close()

	body, err := io.ReadAll(res.Body)
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(string(body))
}

Java

import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/v2/help_center/articles/360026053753/translations/en-us")
		.newBuilder();

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("GET", null)
		.addHeader("Content-Type", "application/json")
		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'GET',
  url: 'https://support.zendesk.com/api/v2/help_center/articles/360026053753/translations/en-us',
  headers: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"
  },
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Python

import requests

url = "https://support.zendesk.com/api/v2/help_center/articles/360026053753/translations/en-us"
headers = {
	"Content-Type": "application/json",
}

response = requests.request(
	"GET",
	url,
	auth=('<username>', '<password>'),
	headers=headers
)

print(response.text)

Ruby

require "net/http"
uri = URI("https://support.zendesk.com/api/v2/help_center/articles/360026053753/translations/en-us")
request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")
request.basic_auth "username", "password"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

Example response(s)

200 OK

// Status 200 OK

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

Create Translation

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

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.

Parameters

Name	Type	In	Required	Description
article_id	integer	Path	true	The unique ID of the article

Code Samples

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"

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://support.zendesk.com/api/v2/help_center/articles/360026053753/translations"
	method := "POST"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"

	client := &http.Client {}
	res, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer res.Body.Close()

	body, err := io.ReadAll(res.Body)
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(string(body))
}

Java

import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/v2/help_center/articles/360026053753/translations")
		.newBuilder();
RequestBody body = RequestBody.create(MediaType.parse("application/json"),
		"""
""");

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("POST", body)
		.addHeader("Content-Type", "application/json")
		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'POST',
  url: 'https://support.zendesk.com/api/v2/help_center/articles/360026053753/translations',
  headers: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"
  },
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Python

import requests

url = "https://support.zendesk.com/api/v2/help_center/articles/360026053753/translations"
headers = {
	"Content-Type": "application/json",
}

response = requests.request(
	"POST",
	url,
	auth=('<username>', '<password>'),
	headers=headers
)

print(response.text)

Ruby

require "net/http"
uri = URI("https://support.zendesk.com/api/v2/help_center/articles/360026053753/translations")
request = Net::HTTP::Post.new(uri, "Content-Type": "application/json")
request.basic_auth "username", "password"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

Example response(s)

201 Created

// Status 201 Created

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

Update Translation

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

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)

Parameters

Name	Type	In	Required	Description
article_id	integer	Path	true	The unique ID of the article
locale	string	Path	true	Mandatory locale parameter

Code Samples

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"

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://support.zendesk.com/api/v2/help_center/articles/360026053753/translations/en-us"
	method := "PUT"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"

	client := &http.Client {}
	res, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer res.Body.Close()

	body, err := io.ReadAll(res.Body)
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(string(body))
}

Java

import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/v2/help_center/articles/360026053753/translations/en-us")
		.newBuilder();
RequestBody body = RequestBody.create(MediaType.parse("application/json"),
		"""
""");

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("PUT", body)
		.addHeader("Content-Type", "application/json")
		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'PUT',
  url: 'https://support.zendesk.com/api/v2/help_center/articles/360026053753/translations/en-us',
  headers: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"
  },
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Python

import requests

url = "https://support.zendesk.com/api/v2/help_center/articles/360026053753/translations/en-us"
headers = {
	"Content-Type": "application/json",
}

response = requests.request(
	"PUT",
	url,
	auth=('<username>', '<password>'),
	headers=headers
)

print(response.text)

Ruby

require "net/http"
uri = URI("https://support.zendesk.com/api/v2/help_center/articles/360026053753/translations/en-us")
request = Net::HTTP::Put.new(uri, "Content-Type": "application/json")
request.basic_auth "username", "password"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

Example response(s)

200 OK

// Status 200 OK

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

Delete Translation

• DELETE /api/v2/help_center/translations/{translation_id}

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

Allowed for

• Agents

Parameters

Name	Type	In	Required	Description
translation_id	integer	Path	true	The unique ID of the translation

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/v2/help_center/translations/{translation_id}.json \
  -v -u {email_address}:{password} -X DELETE

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://support.zendesk.com/api/v2/help_center/translations/1234"
	method := "DELETE"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"

	client := &http.Client {}
	res, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer res.Body.Close()

	body, err := io.ReadAll(res.Body)
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(string(body))
}

Java

import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/v2/help_center/translations/1234")
		.newBuilder();

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("DELETE", null)
		.addHeader("Content-Type", "application/json")
		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'DELETE',
  url: 'https://support.zendesk.com/api/v2/help_center/translations/1234',
  headers: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"
  },
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Python

import requests

url = "https://support.zendesk.com/api/v2/help_center/translations/1234"
headers = {
	"Content-Type": "application/json",
}

response = requests.request(
	"DELETE",
	url,
	auth=('<username>', '<password>'),
	headers=headers
)

print(response.text)

Ruby

require "net/http"
uri = URI("https://support.zendesk.com/api/v2/help_center/translations/1234")
request = Net::HTTP::Delete.new(uri, "Content-Type": "application/json")
request.basic_auth "username", "password"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

Example response(s)

204 No Content

// Status 204 No Content

null