Getting started

Introduction

The Translations API was created so that localized string are being managed by the RAIL and allows other (third-party) apps to retrieve string values in different languages by using a translation key without needing to store them.

How it’s done is by using the android broadcast system. It will send out a broadcast when the RAIL (re)starts or if an app has been installed and will ask to register it’s translations to the RAIL.

This section describes how you can add, update and get translations from the Translations API.

Add translations

Translations are added to the API in the form of a key, category, list of translations.

Publish topic

zbos/translations/add

Payload example 1

Add multiple translations at once.

{
  "key": "a3e19d",
  "category": "default",
  "language": "en-US",
  "translations": [
    "pref_title_base_settings": "Base settings",
    "pref_title_string": "String",
    "pref_summary_required_string": "This is a required string type setting.",
    "pref_title_integer": "Integer",
    "pref_summary_integer": "This is an integer type setting.",
    "pref_title_number": "Number",
    "pref_summary_number": "This is a number type setting.",
    "pref_title_boolean": "Boolean",
    "pref_summary_boolean": "This is a boolean type setting.",
    "pref_title_select_single": "Select single",
    "pref_title_select_single_option_1": "Option 1",
    "pref_title_select_single_option_2": "Option 2",
    "pref_summary_select_single": "This is a select single type setting.",
    "pref_title_select_multi": "Select multi",
    "pref_title_select_multi_option_1": "Option 1",
    "pref_title_select_multi_option_2": "Option 2",
    "pref_title_select_multi_option_3": "Option 3",
    "pref_summary_select_multi": "This is a select multi type setting",
    "pref_title_base_subcategory_settings": "Base subcategory settings",
    "pref_title_classroom_number": "Classroom number"
    "app_category_title_zbos": "zbos",
    "app_category_title_apps": "apps",
    "pref_header_base_application": "Base",
    "app_action_settings": "Settings",
    "app_action_start_action": "Start action"
  ]
}

Payload example 2

Add a file containing translations.

{
  "key": "a3e19d",
  "file": "path/to/default_translations.json"
}

The file contents:

// default_translations.json
{
  "category": "default",
  "language": "en-US",
  "translations": [
    "pref_title_base_settings": "Base settings",
    "pref_title_string": "String",
    "pref_summary_required_string": "This is a required string type setting.",
    "pref_title_integer": "Integer",
    "pref_summary_integer": "This is an integer type setting.",
    "pref_title_number": "Number",
    "pref_summary_number": "This is a number type setting.",
    "pref_title_boolean": "Boolean",
    "pref_summary_boolean": "This is a boolean type setting.",
    "pref_title_select_single": "Select single",
    "pref_title_select_single_option_1": "Option 1",
    "pref_title_select_single_option_2": "Option 2",
    "pref_summary_select_single": "This is a select single type setting.",
    "pref_title_select_multi": "Select multi",
    "pref_title_select_multi_option_1": "Option 1",
    "pref_title_select_multi_option_2": "Option 2",
    "pref_title_select_multi_option_3": "Option 3",
    "pref_summary_select_multi": "This is a select multi type setting",
    "pref_title_base_subcategory_settings": "Base subcategory settings",
    "pref_title_classroom_number": "Classroom number"
    "app_category_title_zbos": "zbos",
    "app_category_title_apps": "apps",
    "pref_header_base_application": "Base",
    "app_action_settings": "Settings",
    "app_action_start_action": "Start action"
  ]
}

Reponse

{"success":true} // true if success, false if fail.

Get translations

Publish topic

zbos/translations/get

Payload example 1

Fetch all translations for a specific category.

{
  "key": "c63737",
  "category": "default",
  "language": "en-US"
}

Response

{
  "translations": [
    "pref_title_base_settings": "Base settings",
    "pref_title_string": "String",
    "pref_summary_required_string": "This is a required string type setting.",
    "pref_title_integer": "Integer",
    "pref_summary_integer": "This is an integer type setting.",
    "pref_title_number": "Number",
    "pref_summary_number": "This is a number type setting.",
    "pref_title_boolean": "Boolean",
    "pref_summary_boolean": "This is a boolean type setting.",
    "pref_title_select_single": "Select single",
    "pref_title_select_single_option_1": "Option 1",
    "pref_title_select_single_option_2": "Option 2",
    "pref_summary_select_single": "This is a select single type setting.",
    "pref_title_select_multi": "Select multi",
    "pref_title_select_multi_option_1": "Option 1",
    "pref_title_select_multi_option_2": "Option 2",
    "pref_title_select_multi_option_3": "Option 3",
    "pref_summary_select_multi": "This is a select multi type setting",
    "pref_title_base_subcategory_settings": "Base subcategory settings",
    "pref_title_classroom_number": "Classroom number"
    "app_category_title_zbos": "zbos",
    "app_category_title_apps": "apps",
    "pref_header_base_application": "Base",
    "app_action_settings": "Settings",
    "app_action_start_action": "Start action"
  ]
}

Payload example 2

Fetch a few specific translations keys in from a category

{
  "key": "c63737",
  "category": "default",
  "language": "en-US",
  "translation_keys": [
    "pref_title_base_settings",
    "pref_title_base_subcategory_settings"
  ]
}

Response

{
  "translations": [
    "pref_title_base_settings": "Base settings",
    "pref_title_base_subcategory_settings": "Base subcategory settings"
  ]
}

Payload example 2

Fetch spefcific translations from multiple categories. Notice how the category is combined with the translation key using the dot notation.

{
  "key": "c63737",
  "language": "en-US",
  "translation_keys": [
    "default.pref_title_base_settings",
    "non_default.pref_title_base_settings"
  ]
}

Update translations

Publish topic

zbos/translations/update

Payload example

{
  "key": "8c51b6",
  "category": "default",
  "language": "en-US",
  "translations": [
    "app_action_start_action": "Perform action",
    "pref_title_classroom_number": "Classroom nr."
  ],
}

Response

zbos/translations/update/response/{key}

{"success":true} // true if succeeded, false if failed

Changed event

zbos/translations/changed/event/{category}

{
  "category": "default",
  "language": "en-US"
}

Reset translations

Publish topic

zbos/translations/reset

Payload example

{
  "key": "c4929f",
  "category": "default",
  "language": "en-US"
}

Result

zbos/translations/reset/response/{key}

{"success":true} // true if succeeded, false if failed