Redirect Notice

Redirect Notice

The page you requested has been relocated to Player Docs.

Localization

This tutorial shows how to properly handle localization in AMP.

The tutorial will cover the following topics:

  1. Setting up a language.
  2. Available localized strings.
  3. Extending available languages.

1. Setting up a Language

By default, AMP will use the browser's language settings. However this can be overridden by providing a ISO 639-1 or ISO 639-2 language code in the attribute language as part of the configuration object.

var config = {
	language: "es"
};

The player supports by default the following language sets:

  • English
  • Spanish
  • French

If the player can not find a matching language set, it will default to English. This too can be overridden in the config by providing a ISO 639-1 language code in the configuration defaults object.

var config = {
	defaults: {
		language: "es"
	}
};

2. Available localized strings

A full list of available message keys can be found by querying the player's l10n property:

console.log(amp.l10n);

The previous command will yield a result similar to the object below:

{
  AD: "Ad",
  CASUAL: "Casual",
  CHI: "Chinese",
  CLOSED_CAPTIONING: "Closed Captioning",
  COLOR_BLACK: "Black",
  COLOR_BLUE: "Blue",
  COLOR_CYAN: "Cyan",
  COLOR_GREEN: "Green",
  COLOR_MAGENTA: "Magenta",
  COLOR_RED: "Red",
  COLOR_WHITE: "White",
  COLOR_YELLOW: "Yellow",
  CURRENT: "Current",
  CURSIVE: "Cursive",
  DE: "German",
  DEU: "German",
  EDGE_DEPRESSED: "Depressed",
  EDGE_LEFT_SHADOW: "Left Drop Shadow",
  EDGE_NONE: "None",
  EDGE_RAISED: "Raised",
  EDGE_RIGHT_SHADOW: "Right Drop Shadow",
  EDGE_UNIFORM: "Uniform",
  EN: "English",
  ENG: "English",
  ENTER_FULLSCREEN: "Toggle Fullscreen Mode",
  ERROR: "Error",
  ERROR_ABORTED: "Media Aborted",
  ERROR_DECODE: "Decode Error",
  ERROR_DEFAULT: "An error has occurred",
  ERROR_NETWORK: "Network Error",
  ERROR_SRC: "Source not supported",
  ES: "Spanish",
  EXIT_FULLSCREEN: "Exit Fullscreen Mode",
  FR: "French",
  FRA: "French",
  FRE: "French",
  FULLSCREEN: "Fullscreen",
  GER: "German",
  GO_LIVE: "GO LIVE",
  IT: "Italian",
  ITA: "Italian",
  JA: "Japanese",
  JPN: "Japanese",
  JUMP_AHEAD: "Jump Ahead",
  JUMP_BACK: "Jump Back",
  KO: "Korean",
  KOR: "Korean",
  LIVE: "LIVE",
  MONOSPACED_SANS_SERIF: "Monospaced Sans-Serif",
  MONOSPACED_SERIF: "Monospaced Serif",
  MUTE: "Mute",
  OF: "of",
  OPTION_BACKGROUND_COLOR: "Background Color",
  OPTION_BACKGROUND_OPACITY: "Background Opacity",
  OPTION_EDGE_COLOR: "Edge Color",
  OPTION_EDGE_OPACITY: "Edge Opacity",
  OPTION_EDGE_STYLE: "Character Edge Style",
  OPTION_FONT_COLOR: "Font Color",
  OPTION_FONT_FAMILY: "Font Family",
  OPTION_FONT_OPACITY: "Font Opacity",
  OPTION_FONT_SIZE: "Font Size",
  OPTION_SCROLL_TYPE: "Scroll Type",
  OPTION_WINDOW_COLOR: "Window Color",
  OPTION_WINDOW_OPACITY: "Window Opacity",
  PAUSE: "Pause",
  PLAY: "Play",
  PLAYBACK_RATE: "Playback Rate",
  PREVIEW: "Preview",
  PROPORTIONAL_SANS_SERIF: "Proportional Sans-Serif",
  PROPORTIONAL_SERIF: "Proportional Serif",
  QUALITY_AUTO: "Auto",
  REPLAY: "Replay",
  REWIND: "Rewind",
  RU: "Russian",
  RUS: "Russian",
  SCROLL_PAINTON: "Paint-on",
  SCROLL_POPOUT: "Pop-out",
  SCROLL_ROLLON: "Roll-on",
  SEEK: "Seek",
  SEEK_TO: "Seek to",
  SETTINGS: "Settings",
  SETTINGS_AUDIO: "Audio",
  SETTINGS_AUTOPLAY: "Autoplay",
  SETTINGS_OPTIONS: "Options",
  SETTINGS_QUALITY: "Quality",
  SETTINGS_SPEED: "Speed",
  SETTINGS_SUBTITLES: "Subtitles",
  SHARE: "Share",
  SLIDER: "Slider",
  SMALL_CAPS: "Small Capitals",
  SPA: "Spanish",
  SPEED_NORMAL: "Normal",
  STREAM_NOT_FOUND: "Stream not found",
  TOGGLE_OFF: "Off",
  UNKNOWN: "Unknown",
  UNMUTE: "Unmute",
  VOLUME: "Volume",
  ZH: "Chinese",
  ZHO: "Chinese"
}

The current list of localized text is also available to data bindings:

amp.evaluateBindings("#{l10n.OF}");

Sometimes it is useful to see which message keys are associated with the player's on screen text. To do this simply provide a falsy value for the config's language property:

var config = {
	language: ""
};

3. Extending Available Languages

Additional language sets can be provided using the config's locales property. Again, each locale should be named using an ISO 639-1 language code.

// provide an additional language set
var config = {
	locales: {
		pt: {
			STREAM_NOT_FOUND: "Erro de Vídeo"
		}
	}
};

Additionaly, the locales property can be used to override existing language sets.

// override an existing message string
var config = {
	locales: {
		en: {
			STREAM_NOT_FOUND: "Sorry, we couldn't find the stream you requested"
		}
	}
};

The locales object can also be used to provide region specific overrides/language sets using ISO standard codes, as before.

// provide country specific overrides
var config = {
	locales: {
		"en-US": {
			OPTION_FONT_COLOR: "Font Color"
		},
		"en-GB": {
			OPTION_FONT_COLOR: "Font Colour"
		}
	}
};

For more information on laguange set naming you can check https://tools.ietf.org/rfc/bcp/bcp47.txt