Multilingual Metadata

This topic provides an overview of adding multilingual metadata to videos for viewers who speak different languages. Multilingual metadata is particularly important to Brightcove Beacon customers, but may be used with Video Cloud videos generally.

Introduction

If you have an international audience (or multilingual within the same country), you may want to provide video metadata such as the title and description in multiple languages.

Video Cloud allows multilingual versions of the following:

  • images
  • text tracks
  • name (via variants)
  • description variants)
  • long description variants)
  • custom field values variants)

Creating a variant

Using the CMS API (Create a Video Variant) you can add and manage an array of variants to provide an alternative name, description, long_description, and map of custom field/values specific to a language.

To create a variant, send a POST request to the endpoint:

https://cms.api.brightcove.com/v1/accounts/{account_id}/videos/{video_id}/variants/
{
  "language": "ja-JA",
  "name": "バーゼル：ライン川",
  "description": "スイス、バーゼルの中心部にあるライン川のパノラマビュー。",
  "long_description": "スイス、バーゼルの中心部にあるライン川のパノラマビュー。",
  "custom_fields": {
    "language": "Japanese"
  }
}

Sample response

 
{
  "language": "ja-JA",
  "name": "バーゼル：ライン川",
  "description": "スイス、バーゼルの中心部にあるライン川のパノラマビュー。",
  "long_description": "スイス、バーゼルの中心部にあるライン川のパノラマビュー。",
  "custom_fields": {
    "language": "Japanese"
  }
}

Getting variants

Get all variants

You can get all the variants for a video by sending a GET request to the endpoint:

https://cms.api.brightcove.com/v1/accounts/{account_id}/videos/{video_id}/variants

Sample response

 
[
  {
    "language": "es-ES",
    "name": "Basilea: el Rin",
    "description": "Vista panorámica del Rin en el centro de Basilea, Suiza.",
    "long_description": "Vista panorámica del Rin en el centro de Basilea, Suiza.",
    "custom_fields": {
    }
  },
  {
    "language": "de-DE",
    "name": "Basel: Der Rhein",
    "description": "Panoramablick auf den Rhein im Zentrum von Basel, Schweiz.",
    "long_description": "Panoramablick auf den Rhein im Zentrum von Basel, Schweiz.",
    "custom_fields": {
    }
  },
  {
    "language": "ja-JA",
    "name": "バーゼル：ライン川",
    "description": "スイス、バーゼルの中心部にあるライン川のパノラマビュー。",
    "long_description": "スイス、バーゼルの中心部にあるライン川のパノラマビュー。",
    "custom_fields": {
      "language": "Japanese"
    }
  }
  ]

Get a particular variant

To get a particular variant, send a GET request to the endpoint:

https://cms.api.brightcove.com/v1/accounts/{account_id}/videos/{video_id}/variants/{language}

Here language is the language code used in the variant, such as de-DE.

Sample response

 
{
  "language": "de-DE",
  "name": "Basel: Der Rhein",
  "description": "Panoramablick auf den Rhein im Zentrum von Basel, Schweiz.",
  "long_description": "Panoramablick auf den Rhein im Zentrum von Basel, Schweiz.",
  "custom_fields": {
  }
}

Updating a variant

You can update a variant by sending a PATCH request to the endpoint:

https://cms.api.brightcove.com/v1/accounts/{account_id}/videos/{video_id}/variants/{language}

Here language is the language code used in the variant, such as de-DE.

You only need to include the fields that are changing. The request body fields are the same as for creating a variant, except that you may not include the language field. (If you do include the language field a VALIDATION_ERROR will be returned.)

Sample request body

 
{
  "name": "Basilea: el Rin",
  "description": "Vista panorámica del Rin en el centro de Basilea, Suiza.",
  "long_description": "Vista panorámica del Rin en el centro de Basilea, Suiza.",
  "custom_fields": {
    "language": "Spanish"
 }
}

Sample response

 
{
  "language": "es-ES",
  "name": "Basilea: el Rin",
  "description": "Vista panorámica del Rin en el centro de Basilea, Suiza.",
  "long_description": "Vista panorámica del Rin en el centro de Basilea, Suiza.",
  "custom_fields": {
    "language": "Spanish"
  }
}

Delete a variant

To delete a variant, send a DELETE request to the endpoint:

https://cms.api.brightcove.com/v1/accounts/{account_id}/videos/{video_id}/variants/{language}

Do not include a request body. A successful deletion, will return a 204 No Content response.

Variants can be retrieved using the Playback API as well as the CMS API. In the Playback API, they are returned when you get a video, as a top-level variants array:

"variants": [
  {
    "language": "de-DE",
    "name": "Basel: Der Rhein",
    "description": "Panoramablick auf den Rhein im Zentrum von Basel, Schweiz.",
    "long_description": "Panoramablick auf den Rhein im Zentrum von Basel, Schweiz.",
    "custom_fields": {}
  },
  {
    "language": "ja-JA",
    "name": "バーゼル：ライン川",
    "description": "スイス、バーゼルの中心部にあるライン川のパノラマビュー。",
    "long_description": "スイス、バーゼルの中心部にあるライン川のパノラマビュー。",
    "custom_fields": {
      "language": "Japanese"
    }
  }
]

Images and text tracks

Images and text tracks for alternate languages can be added using the Dynamic Ingest API. For details, see the following topics: