Contact Support | System Status
Page Contents

    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:


    Page last updated on 15 Dec 2020