API

TermBase API

List, create, update and delete glossary terms, and export a TermBase to TBX or CSV, with the WebTranslateIt TermBase API. 8 min read

The TermBase API is composed of 7 endpoints:

List Terms — list terms
Show Term — show a term
Create Term — create a term
Update Term — update a term
Delete Term — delete a term and its translations
TermBase to TBX — Download all terms to a TBX file
TermBase to CSV — Download all terms to a CSV file

List Terms

This endpoint is accessible by the read-write Project API key and is used to list terms.

/api/projects/:project_token/terms.format [GET]

Where format is one of xml, json, or yaml.

Pagination

This resource is paginated and serves 250 Terms per page. You can specify further page using the ?page parameter. Note that page numbering is 1-based and that omitting the ?page parameter will return the first page.

Link Header

The pagination information is included in the Link header. You can use the Link Header in order to know which page is next and which page is the last one, instead of constructing your own URLs.

For instance, let’s make a curl request to the TermBase API:

bash

curl -I "https://webtranslateit.com/api/projects/PROJECT_TOKEN/terms.json"

The -I parameter indicates that we only care about the headers, not the actual content. In examining the result, you’ll notice some information in the Link header that looks like this:

Link: <https://webtranslateit.com/api/projects/api_key/terms.json?page=2>; rel="next",
  <https://webtranslateit.com/api/projects/api_key/terms.json?page=20>; rel="last"

The possible rel values are:

next: Shows the URL of the immediate next page of results.
last: Shows the URL of the last page of results.
first: Shows the URL of the first page of results.
prev: Shows the URL of the immediate previous page of results.

Here’s another example of the Link Header when browsing the 3rd page:

bash

curl -I "https://webtranslateit.com/api/projects/PROJECT_TOKEN/terms.json?page=3"

Link: <https://webtranslateit.com/api/projects/api_key/terms.json?page=4>; rel="next",
  <https://webtranslateit.com/api/projects/api_key/terms.json?page=9>; rel="last",
  <https://webtranslateit.com/api/projects/api_key/terms.json?page=1>; rel="first",
  <https://webtranslateit.com/api/projects/api_key/terms.json?page=2>; rel="prev"

This resource is paginated and serves 250 Terms per page. In the server response headers, you will find Link, with a link for an API call to the next and last pages.

Parameters

page: Page number.

Example query:

GET/api/projects/:project_token/terms.json

curl "https://webtranslateit.com/api/projects/PROJECT_TOKEN/terms.json"

const response = await fetch(
  'https://webtranslateit.com/api/projects/PROJECT_TOKEN/terms.json'
)
const terms = await response.json()

import requests

response = requests.get(
    "https://webtranslateit.com/api/projects/PROJECT_TOKEN/terms.json"
)
terms = response.json()

require 'net/http'
require 'json'

uri = URI('https://webtranslateit.com/api/projects/PROJECT_TOKEN/terms.json')
terms = JSON.parse(Net::HTTP.get(uri))

<?php
$ch = curl_init('https://webtranslateit.com/api/projects/PROJECT_TOKEN/terms.json');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$terms = json_decode(curl_exec($ch), true);
curl_close($ch);

Example response with JSON:

[
  {
    "id": 1234,
    "text": "User",
    "description": "Someone using the WebTranslateIt service.",
    "created_at": "2010-02-09T23:23:45Z",
    "updated_at": "2011-10-28T13:54:13Z",
  },
  {
    "id": 1235,
    "text": "Segment",
    "description": "A portion of text to translate.",
    "created_at": "2010-02-09T23:23:45Z",
    "updated_at": "2011-10-28T13:54:13Z",
  }
]

Show Term

This endpoint is only accessible by the read-write Project API key and is used to show a term.

/api/projects/:project_token/terms/:term_id.format [GET]

Where format is one of xml, json or yaml.

GET/api/projects/:project_token/terms/:term_id.json

curl "https://webtranslateit.com/api/projects/PROJECT_TOKEN/terms/1234.json"

const response = await fetch(
  'https://webtranslateit.com/api/projects/PROJECT_TOKEN/terms/1234.json'
)
const term = await response.json()

import requests

response = requests.get(
    "https://webtranslateit.com/api/projects/PROJECT_TOKEN/terms/1234.json"
)
term = response.json()

require 'net/http'
require 'json'

uri = URI('https://webtranslateit.com/api/projects/PROJECT_TOKEN/terms/1234.json')
term = JSON.parse(Net::HTTP.get(uri))

<?php
$ch = curl_init('https://webtranslateit.com/api/projects/PROJECT_TOKEN/terms/1234.json');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$term = json_decode(curl_exec($ch), true);
curl_close($ch);

Example response with JSON:

{
  "id": 1234,
  "text": "User",
  "description": "Someone using the WebTranslateIt service.",
  "created_at": "2010-02-09T23:23:45Z",
  "updated_at": "2011-10-28T13:54:13Z",
}

Create Term

This endpoint is only accessible by the read-write Project API key and is used to create a new term.

/api/projects/:project_token/terms [POST]

Parameters

A JSON object modelled after the following:

{
  "text": "Term",
  "description": "An optional description"
}

The description field is optional. If everything goes well, WebTranslateIt will respond with 201 Created in the header and a JSON representation of the term just created in the body.

You can also create one or several Term Translations while creating a Term by passing an optional array of Translation:

{
  "text": "Term",
  "description": "An optional description",
  "translations": [
  {
    "locale": "fr",
    "text": "Terme",
    "description": "La traduction de la description",
    "status": "approved"
  },
  {
    "locale": "es",
    "text": "Terminología",
    "description": "",
    "status": "refused"
  }
  ]
}

In this array of Translation, locale and text are mandatory. status is optional (defaults to proposed).

status can be one of approved, refused or proposed.

POST/api/projects/:project_token/terms

curl -X POST "https://webtranslateit.com/api/projects/PROJECT_TOKEN/terms" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Segment",
    "description": "A unit of text aligned across languages"
  }'

const response = await fetch(
  'https://webtranslateit.com/api/projects/PROJECT_TOKEN/terms',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      text: 'Segment',
      description: 'A unit of text aligned across languages'
    })
  }
)
const term = await response.json()

import requests

response = requests.post(
    "https://webtranslateit.com/api/projects/PROJECT_TOKEN/terms",
    json={
        "text": "Segment",
        "description": "A unit of text aligned across languages",
    },
)
term = response.json()

require 'net/http'
require 'json'

uri = URI('https://webtranslateit.com/api/projects/PROJECT_TOKEN/terms')
response = Net::HTTP.post(uri, {
  text: 'Segment',
  description: 'A unit of text aligned across languages'
}.to_json, 'Content-Type' => 'application/json')
term = JSON.parse(response.body)

<?php
$ch = curl_init('https://webtranslateit.com/api/projects/PROJECT_TOKEN/terms');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'text' => 'Segment',
    'description' => 'A unit of text aligned across languages',
]));
$term = json_decode(curl_exec($ch), true);
curl_close($ch);

Update Term

This endpoint is only accessible by the read-write Project API key and is used to update an existing term.

/api/projects/:project_token/terms/:term_id [PATCH]

Parameters

A JSON object modelled after the following:

json

{
  "text": "Term",
  "description": "An optional description"
}

The description field is optional. Only provided fields will be modified. If everything goes well, WebTranslateIt will respond with 202 Accepted in the header and a JSON representation of the term just updated in the body.

PATCH/api/projects/:project_token/terms/:term_id

curl -X PATCH "https://webtranslateit.com/api/projects/PROJECT_TOKEN/terms/1234" \
  -H "Content-Type: application/json" \
  -d '{ "description": "A unit of text aligned across languages" }'

const response = await fetch(
  'https://webtranslateit.com/api/projects/PROJECT_TOKEN/terms/1234',
  {
    method: 'PATCH',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      description: 'A unit of text aligned across languages'
    })
  }
)
const term = await response.json()

import requests

response = requests.patch(
    "https://webtranslateit.com/api/projects/PROJECT_TOKEN/terms/1234",
    json={"description": "A unit of text aligned across languages"},
)
term = response.json()

require 'net/http'
require 'json'

uri = URI('https://webtranslateit.com/api/projects/PROJECT_TOKEN/terms/1234')
request = Net::HTTP::Patch.new(uri, 'Content-Type' => 'application/json')
request.body = {description: 'A unit of text aligned across languages'}.to_json
response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) }
term = JSON.parse(response.body)

<?php
$ch = curl_init('https://webtranslateit.com/api/projects/PROJECT_TOKEN/terms/1234');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'description' => 'A unit of text aligned across languages',
]));
$term = json_decode(curl_exec($ch), true);
curl_close($ch);

Delete Term

This endpoint is only accessible by the read-write Project API key and is used to delete a term and its translations.

/api/projects/:project_token/terms/:term_id [DELETE]

Deleting a Term also deletes its Term Translations.

DELETE/api/projects/:project_token/terms/:term_id

curl -X DELETE "https://webtranslateit.com/api/projects/PROJECT_TOKEN/terms/1234"

await fetch(
  'https://webtranslateit.com/api/projects/PROJECT_TOKEN/terms/1234',
  { method: 'DELETE' }
)

import requests

requests.delete(
    "https://webtranslateit.com/api/projects/PROJECT_TOKEN/terms/1234"
)

require 'net/http'

uri = URI('https://webtranslateit.com/api/projects/PROJECT_TOKEN/terms/1234')
Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
  http.request(Net::HTTP::Delete.new(uri))
end

<?php
$ch = curl_init('https://webtranslateit.com/api/projects/PROJECT_TOKEN/terms/1234');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_exec($ch);
curl_close($ch);

TermBase to TBX

This endpoint is accessible by both the read-write and read-only Project API keys and is used to download a termbase as a TermBase Exchange file (TBX).

/api/projects/:project_token/terms/to_tbx [GET]

For more information about TBX files, please refer to the TBX specifications.

An optional parameter, locale=xx can be passed to get a TBX file containing only the source_locale and locale language pairs.

GET/api/projects/:project_token/terms/to_tbx

curl -o termbase.tbx \
  "https://webtranslateit.com/api/projects/PROJECT_TOKEN/terms/to_tbx?locale=fr"

import { writeFile } from 'node:fs/promises'

const response = await fetch(
  'https://webtranslateit.com/api/projects/PROJECT_TOKEN/terms/to_tbx?locale=fr'
)
await writeFile('termbase.tbx', await response.text())

import requests

response = requests.get(
    "https://webtranslateit.com/api/projects/PROJECT_TOKEN/terms/to_tbx",
    params={"locale": "fr"},
)
with open("termbase.tbx", "wb") as target:
    target.write(response.content)

require 'net/http'

uri = URI('https://webtranslateit.com/api/projects/PROJECT_TOKEN/terms/to_tbx')
uri.query = URI.encode_www_form(locale: 'fr')
File.write('termbase.tbx', Net::HTTP.get(uri))

<?php
$ch = curl_init('https://webtranslateit.com/api/projects/PROJECT_TOKEN/terms/to_tbx?locale=fr');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
file_put_contents('termbase.tbx', curl_exec($ch));
curl_close($ch);

TermBase to CSV

This endpoint is accessible by both the read-write and read-only Project API keys and is used to download a termbase as a Comma Separated Value file (CSV).

/api/projects/:project_token/terms/to_csv [GET]

For more information about CSV files, please refer to the CSV specifications.

An optional parameter, locale=xx can be passed to get a CSV file containing only the source_locale and locale language pairs.

GET/api/projects/:project_token/terms/to_csv

curl -o termbase.csv \
  "https://webtranslateit.com/api/projects/PROJECT_TOKEN/terms/to_csv?locale=fr"

import { writeFile } from 'node:fs/promises'

const response = await fetch(
  'https://webtranslateit.com/api/projects/PROJECT_TOKEN/terms/to_csv?locale=fr'
)
await writeFile('termbase.csv', await response.text())

import requests

response = requests.get(
    "https://webtranslateit.com/api/projects/PROJECT_TOKEN/terms/to_csv",
    params={"locale": "fr"},
)
with open("termbase.csv", "wb") as target:
    target.write(response.content)

require 'net/http'

uri = URI('https://webtranslateit.com/api/projects/PROJECT_TOKEN/terms/to_csv')
uri.query = URI.encode_www_form(locale: 'fr')
File.write('termbase.csv', Net::HTTP.get(uri))

<?php
$ch = curl_init('https://webtranslateit.com/api/projects/PROJECT_TOKEN/terms/to_csv?locale=fr');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
file_put_contents('termbase.csv', curl_exec($ch));
curl_close($ch);

Documentation

TermBase API

List Terms#

Pagination#

Link Header#

Parameters#

Example query:#

Example response with JSON:#

Show Term#

Create Term#

Parameters#

Update Term#

Parameters#

Delete Term#

TermBase to TBX#

TermBase to CSV#

List Terms

Pagination

Link Header

Parameters

Example query:

Example response with JSON:

Show Term

Create Term

Parameters

Update Term

Parameters

Delete Term

TermBase to TBX

TermBase to CSV