Interface translations

Change the words your help center's interface shows, such as the search placeholder, headings, buttons and the widget's messages, in any of your languages. You read the catalogue of interface strings with your help center's values, and write your own wording for the strings and languages you choose.

These are not article translations. An article's title and body in each language live on the article itself: write them with PATCH /v1/articles/{articleId} and a language map per field (see Articles).

Endpoints

These endpoints work on every plan, with API keys and OAuth access tokens. A Read only key on a write answers 403 with insufficient_scope.

How interface strings work

• One catalogue of keys for every help center. Each string has a key, such as site.search_placeholder or widget.buttons.send, and a built-in default. The defaults are in English. GET /v1/translations lists every key.

• Your values override the default, per language. A German value shows only on German pages. A language you have no value for shows the default, in English.

• A language shows only when it is enabled. You can store values for any supported language, but readers see them only in the languages your help center has (see Add a language to your help center).

• Texts set in your design win. Where your help center's design sets its own text, such as a search field with a placeholder of its own, readers see that text instead of the interface string. Change those in the template editor (see Translate texts in your design).

• The widget uses its own English. For English, the widget always shows its built-in texts, so an English value for a widget.* key is stored but never shown. The write succeeds with a warning.

• There is no publish step. Pages usually show a change on their next load, but a page served from a cache can show the previous wording for a while.

The same strings are on the dashboard's Localization page (see Translate buttons and labels).

The translation object

For a key that is not in the catalogue, label, description, default and group are null. The groups:

List interface strings

Get every string in the catalogue, in the order of the Localization page, with your values.

To see what you have changed in German:

curl -sS "https://api.helpcenter.io/v1/translations?only_overridden=1&lang=de" \
  -H "apikey: $HELPCENTER_API_KEY" \
  -H "Accept: application/json"

The response lists only the strings with a German value, and meta tells you the help center's languages:

{
  "status": "success",
  "translations": [
    {
      "key": "site.search_placeholder",
      "label": "Search Field Placeholder",
      "description": "The placeholder text inside search fields that have not been given a custom placeholder.",
      "default": "How can we help?",
      "group": "search",
      "catalogued": true,
      "text": {
        "de": "Wie können wir helfen?"
      }
    },
    {
      "key": "site.skip_to_content",
      "label": "Skip to Content Link",
      "description": "The keyboard link that jumps past the header straight to the content. Visible only while focused.",
      "default": "Skip to content",
      "group": "accessibility",
      "catalogued": true,
      "text": {
        "de": "Zum Inhalt springen"
      }
    }
  ],
  "meta": {
    "items_count": 3,
    "overridden_count": 3,
    "default_language": "en",
    "site_languages": [
      "en",
      "de"
    ]
  }
}

Two of the three strings are shown. meta has items_count (strings returned), overridden_count (of those, how many have a value), default_language and site_languages (the default language first, then the others enabled on the help center). Without group, the list ends with any stored values for keys that are no longer in the catalogue, marked "catalogued": false.

Write several strings

Send translations: an object whose keys are string keys and whose values are language maps. Each language you send is merged into what is stored; languages you leave out stay as they are.

• Up to 250 keys per request. Each language map needs at least one language, and each value can be up to 2,000 characters.

• null or an empty string removes your value for that language, so readers see the default again. When a string's last language is removed, the string no longer counts as overridden.

• Every key must be in the catalogue, or already have a stored value in your help center. Otherwise the answer is 422 with Unknown interface-string key "site.categories_heading". Writable keys are the ones GET /v1/translations lists.

• One invalid entry fails the whole request with 422, and nothing is written.

• Values are trimmed, so a value of only spaces removes the language too.

The response lists every key you sent, with its values after the write, and meta:

The two warnings you can get: an English value for a widget.* key, which the widget never shows, and a language your help center has not enabled. Writing {"widget.buttons.send": {"en": "Send", "fr": "Envoyer"}} on a help center without French answers with this meta:

{
  "items_count": 1,
  "keys_written": 1,
  "keys_removed": 0,
  "warnings": [
    "The widget does not read English overrides — it uses its built-in English copy — so the \"en\" value stored for widget.buttons.send will not render.",
    "Stored, but not rendered yet: fr is not an enabled language on this help center."
  ]
}

Write one string

Send text, the language map for the key in the path. The rules are the same as for several strings.

A key that is not in the catalogue, and has no stored value, answers 404 with the Unknown interface-string key message. A body that is not a language map answers 422, for example text must be an object keyed by language code. for {"text": "Suchen"}. To go back to the default text in one language, send null for it:

curl -sS -X POST "https://api.helpcenter.io/v1/translations/site.search_placeholder" \
  -H "apikey: $HELPCENTER_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"text": {"de": null}}'

Errors

Validation errors come as {"status": "validation_error", "message": "The request could not be accepted.", "errors": {…}}, with each message under the entry it concerns, such as translations.site.search_placeholder.pt-BR. For the shapes every endpoint shares, see Errors.

Related

• Requests and responses

• Articles