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