Skip to content

Latest commit

 

History

History
156 lines (106 loc) · 6.29 KB

languages.md

File metadata and controls

156 lines (106 loc) · 6.29 KB

Languages

Multiple language support allows for users of non-English locales to natively interact with the Video.js player.

For an up-to-date list of the languages Video.js supports, see the languages folder (lang). These JSON files are converted to JavaScript during the Video.js build process.

Table of Contents

Using Video.js Languages

Video.js ships with multiple translations (in dist/lang/) in JavaScript files. Each of these files can be included in a web page to provide support for that language in all Video.js players:

<script src="//example.com/path/to/video.min.js"></script>
<script src="//example.com/path/to/lang/es.js"></script>

Contributing to Video.js Translations

We welcome new translations and improvements to existing ones! Please see the contributing document to get started contributing to Video.js and continue reading for specifics on how to contribute to translations of Video.js...

JSON Format

Video.js uses a JSON object to describe a language, where the keys are English and the values are the target language. For example, a Spanish translation might look like this:

{
  "Play": "Reproducción",
  "Pause": "Pausa",
  "Current Time": "Tiempo reproducido",
  "Duration Time": "Duración total",
  "Remaining Time": "Tiempo restante",
  ...
}

File Naming

Translations are always found in the lang/ directory.

Each file's name should be the standard language code that is most appropriate. For example, "es" for Spanish or "zh-CN" for Chinese.

Finally, each file's extension is always .json.

Updating an Existing Translation

If there is a missing translation, mistake, or room for improvement in an existing translation, don't hesitate to open a pull request!

  1. Edit the relevant JSON file and make the necessary changes.
  2. Verify the language compiles by running grunt dist.
  3. Verify the translation appears properly in the player UI.
  4. Run grunt check-translations to update the missing translation document.
  5. Commit and open a pull request on GitHub.

Writing a New Translation

The process for writing an entirely new translation is virtually identical to the process for updating an existing translation except that the new translation JSON file needs to be created.

The template for new language files is the English file (lang/en.json). This file is always up-to-date with strings that need translations.

The first step to writing a new translation is to copy the English file:

cp lang/en.json lang/${NEW_LANG_CODE}.json

Otherwise, the process is the same as updating an existing translation.

Advanced Language Usage

The instructions above for using Video.js languages should be sufficient for the majority of use-cases. However, languages can be provided at runtime.

In each case, these custom language definitions take precedence over any Video.js-provided languages!

Adding Languages via the API

In addition to the stand-alone scripts provided by Video.js, the API supports manual definition of new languages via the addLanguage method. It takes two arguments: the standard language code and a language definition object.

videojs.addLanguage('es', {
  'Play': 'Reproducción',
  'Pause': 'Pausa',
  'Current Time': 'Tiempo reproducido',
  'Duration Time': 'Duración total',
  'Remaining Time': 'Tiempo restante',
  ...
});

Per-Player Languages

In addition to providing languages to Video.js itself, individual Player instances can be provided custom language support via the languages option:

// Provide a custom definition of Spanish to this player.
videojs('my-player', {
  languages: {
    es: {...}
  }
});

Setting Default Player Language

Player instances can also have a default language via the language option:

// Set the default language to Spanish for this player.
videojs('my-player', {
  language: 'es'
});

Additionally, the language method of the player can be used to set the language after instantiation (e.g., language('es')). However, this is not recommended as it does not update the UI in place. Setting the language via options is always preferred.

Determining Player Language

The player language is set to one of the following in descending priority:

  • The language specified in options
  • The language specified by the closest element with a lang attribute. This could be the player itself or a parent element. Usually, the document language is specified on the <html> tag.
  • Browser language preference; the first language if more than one is configured
  • English

Internal Language Selection

  • Language codes are considered case-insensitively (e.g. en-US == en-us).
  • If there is no match for a language code with a subcode (e.g. en-us), a match for the primary code (e.g. en) is used if available.

References

For information on translation/localization in plugins, see the plugins guide.

Standard languages codes are defined by the IANA.

For all existing/supported languages, please see the languages lolder (lang/) folder located in the project root.