<pclass="legacydocsnote">This documentation is for an outdated version of Video.js. See <ahref="https://docs.videojs.com/tutorial-languages.html">documentation for the current release</a>.
<p>Multiple language support allows for users of non-English locales to natively interact with the displayed player. Video.js will compile multiple language files (see below) and instantiate with a global dictionary of language key/value support. Video.js player instances can be created with per-player language support that amends/overrides these default values. Player instances can also hard-set default languages to values other than English as of version 4.7.</p>
<h2id="creating-the-language-file">Creating the Language File</h2>
<p>Video.js uses key/value object dictionaries in JSON form.</p>
<p>An English lang file is at <ahref="https://github.com/videojs/video.js/tree/master/lang/en.json">/lang/en.json</a> which should be used as a template for new files. This will be kept up to date with strings in the core player that need localizations.</p>
<p>A sample dictionary for Spanish <code>['es']</code> would look as follows:</p>
"Close Modal Dialog": "Cerca de diálogo modal",
"You aborted the video playback": "Ha interrumpido la reproducción del vídeo.",
"A network error caused the video download to fail part-way.": "Un error de red ha interrumpido la descarga del vídeo.",
"The video could not be loaded, either because the server or network failed or because the format is not supported.": "No se ha podido cargar el vídeo debido a un fallo de red o del servidor o porque el formato es incompatible.",
"The video playback was aborted due to a corruption problem or because the video used features your browser did not support.": "La reproducción de vídeo se ha interrumpido por un problema de corrupción de datos o porque el vídeo precisa funciones que su navegador no ofrece.",
"No compatible source was found for this video.": "No se ha encontrado ninguna fuente compatible con este vídeo."
}
</code></pre>
<p>Notes:</p>
<ul>
<li>The file name should always be in the format <code>XX.json</code>, where <code>XX</code> is the language code. This should be a two letter code (for options see the bottom of this document) except for cases where a more specific code with sub-code is appropriate, e.g. <code>zh-CN.lang</code>.</li>
<li>For automatic inclusion at build time, add your language file to the <code>/lang</code> directory (see 'Adding Languages to Video.js below').</li>
</ul>
<h2id="adding-languages-to-video-js">Adding Languages to Video.js</h2>
<p>Additional language support can be added to Video.js in multiple ways.</p>
<ol>
<li>Create language scripts out of your JSON objects by using our custom grunt task <code>vjslanguages</code>. This task is automatically run as part of the default grunt task in Video.JS, but can be configured to match your <code>src</code>/<code>dist</code> directories if different. Once these scripts are created, just add them to your DOM like any other script.</li>
</ol>
<p>NOTE: These need to be added after the core Video.js script.</p>
<ol>
<li>Add your JSON objects via the videojs.addLanguage API. Preferably in the HEAD element of your DOM or otherwise prior to player instantiation.</li>
"Close Modal Dialog": "Cerca de diálogo modal",
"You aborted the video playback": "Ha interrumpido la reproducción del vídeo.",
"A network error caused the video download to fail part-way.": "Un error de red ha interrumpido la descarga del vídeo.",
"The video could not be loaded, either because the server or network failed or because the format is not supported.": "No se ha podido cargar el vídeo debido a un fallo de red o del servidor o porque el formato es incompatible.",
"The video playback was aborted due to a corruption problem or because the video used features your browser did not support.": "La reproducción de vídeo se ha interrumpido por un problema de corrupción de datos o porque el vídeo precisa funciones que su navegador no ofrece.",
"No compatible source was found for this video.": "No se ha encontrado ninguna fuente compatible con este vídeo."
});
</script>
</head>
</code></pre>
<ol>
<li>During a Video.js player instantiation. Adding the languages to the configuration object provided in the <code>data-setup</code> attribute.</li>
<li>This will add your language key/values to the Video.js player instances individually. If these values already exist in the global dictionary via the process above, those will be overridden for the player instance in question.</li>
</ul>
<h2id="setting-default-language-in-a-video-js-player">Setting Default Language in a Video.js Player</h2>
<p>During a Video.js player instantiation you can force it to localize to a specific language by including the locale value into the configuration object via the <code>data-setup</code> attribute. Valid options listed at the bottom of the page for reference.</p>
<h2id="determining-player-language">Determining Player Language</h2>
<p>The player language is set to one of the following in descending priority:</p>
<ul>
<li>The language specified in setup options as above</li>
<li>The language specified by the closet element with a <code>lang</code> attribute. This could be the player itself or a parent element. Usually the document language is specified on the <code>html</code> tag.</li>
<li>Browser language preference (the first language if more than one is configured)</li>
<li>'en'</li>
</ul>
<p>The player language can be change after instantiation with <code>language('fr')</code>. However localizable text will not be modified by doing this, for best results set the language beforehand.</p>
<li>Language codes are considered case-insensitively (<code>en-US</code> == <code>en-us</code>).</li>
<li>If there is no match for a language code with a subcode (<code>en-us</code>), a match for the primary code (<code>en</code>) is used if available.</li>
</ul>
<h2id="localization-in-plugins">Localization in Plugins</h2>
<p>When you're developing a plugin, you can also introduce new localized strings. Simply wrap the string with the player's <code>localize</code> function:</p>
<p>The following is a list of official language codes.</p>
<p><strong>NOTE:</strong> For supported language translations, please see the <ahref="https://github.com/videojs/video.js/tree/master/lang">Languages Folder (/lang)</a> folder located in the project root.</p>
