Localization and the Player Management APIs

localized-player-config.js

/* First option: make localization an "opportunity" for every plugin */
{
  "errors": {
    "localizations": {
      "es": {
         "1": {
           "headline": "Espanol!",
           "message": "Cual es tu numero de telefono?"
         }
      }
    }
  },
  "localized2": {
    "localizations": {
      "de": "uh-oh?"
    }
  },
  "localized3": {
    /* I forgot to include a localization. What happens? */
  },

  /* old syntax */
  "plugins": [{
    "name": "errors",
    "options": {}
  }]
}

/* second option: include locale at the player level */
{
  "locale": "es",
  "localizations": {
    "es": {
      "technical details": "Details de Techincale"
      /* what happens if two plugins define the same key? */
      "help": "ayuda"
    }
  }
}
// in the plugin:
el.setAttribute('data-i18n', player.options().localizations[player.options().locale]['technical details']);
// or maybe at the player level:
player.localize() // do the stuff above by walking all over the player element tree

/* third option: */
{
  "locale": "es" /* this player doesn't switch at runtime? */
}
// plugins need to add their localization messages...
player.localizations = videojs.util.mergeOptions(player.localizations, plugin.options().localizations);
// then the player will whip through the DOM and update the text
player.locale('es'); // kicked off by SVT

{
  "locales": ["es", ["en", "de"]],

  "plugins": [{
    "name": "customplugin"
  }]
}

// CSS Solution
div:before {
  content: attr(data-i18n);
}
<:before>Utopia Soluccion</:before><div data-i18n="Utopia Solution" data-i18n-es="Utopia Soluccion"></div>

// what if videojs.Component locale-aware?
1. Figure out what page locale is
2. Check if we have text for that locale
  - * if so, render with the localized text *
  - if not, use the default text

// How would a component find out about its localizations?
var defaults = {
  locale: ["en", ["es"]], // [[]] ?
  localizations: {
    en: {}
  }
};
new Component({
  localizations: {
    "es": {
      "key": "value"
    },
    "en": {}
  }
});

// localizations for slider, button, progress-control independently
// you can selectively include the localizations for individual components that you want.
// for instance, slider.es.js, button.es.js instead of just including one mega-l20n file
mergeOptions(defaults, options);

// we could allow custom builds to be created that selectively included translations
$ grunt locales=['en', 'de']
locale.es.js, locale.en.js, locale.de.js

// inside locale.es.js:
videojs.Component.options.l20n.es = {
  "play": "la playa"
};
videojs.Slider.options.localizations.es = {
  "100%": "100 percento!"
};
videojs.ProgressControl.options.l20n.es = 
  videojs.util.mergeOptions(videojs.Slider.options.l20n, {
    "200%": "200 percento!"
  });

// inside slider.js:
createEl: function()  {
  var locale = player.options().locale;
  return "<div>" + videojs.Slider.options.localization[locale]['div text'] + "</div>";
}

createEl: function() {
  return "<div>${div text}</div>"
}

// plugin authors can specify their own l20n stuff:
// making a new progress control component, custom-progress.es.js:
videojs.CustomProgress.options.l20n.es = 
  videojs.util.mergeOptions(videojs.ProgressControl.options.l20n, {
    "custom message": "custom"
  });

/* We like this: one global l20n namespace */
// in locale.es.js:
videojs.options.l20n.es = {
  '100%': '100 percento!'
};

// in custom-progress.es.js:
videojs.options.l20n.es['custom message'] = 'custom!'

/* Synopsis */
Things we need to build:
- The player needs to accept a locale option and default it to something reasonable if one is not set
- In component, we need createEl to do text replacement for the locale
  - if the key isn't in the locale hash, plop the key in unmodified
    * check best practices for creating "localization" dictionaries
    * keys become part of the API so we have to be careful about changing them
- Update gruntfile so that alternate locale distributions can be created
- Update Yoeman generator to create an english dictionary (at least) by default and the appropriate grunt stuff

Out of scope:
- providing a runtime setting to switch locales (Tom concurs)