[Salvador Villalon] Add i18n to Piskel

[salvillalon45]

Intro

My name is Salvador Villalon Jr and I am an Advanced Application Engineering Analyst at Accenture working
as part of the pro-bono pogram with Code.org

Overview

Why Was This Branch Created?

Back in Dec 1st, 2015, Julian Descottes created a GitHub issue on the Piskel Repo explaining how they
wanted to add internationalization (i18n) support to the Piskel App

The problem was that all of the strings are hard coded in English and their goals was to replace hard coded strings
by a mechanism that will load string dyanmically through the help of the an i18n framework and architecture

The Code.org team decided to help out since they rely on the Piskel editor and need it to be translated as well

What This Branch Contains

It contains the code that sets up the i18n framework & architecture and uses it for the translations throughout the app.
This are the steps we took to implement i18n

1. Load String Into the Window Object

• The available strings are in i18n/locales directory and each locale has its own JSON file.
  For example: en_us.json where en is English and us is United States.
• The JSON files are converted to Javascript files during the build in tasks/build-i18n.js. The MessageFormat library is used to convert the static JSON strings into Javascript functions so dynamic content can be injected into the strings.
• Then while the screen shows the Loading Piskel... and the black screen the grunt task build-i18n is running and the strings are available once the black screen disappears and
  the editor is available

2. Retrieve The Locale Code and Use It

• In app.js this piece of code allows us to retrieve the code and load the designated strings. We then set the strings we retrieved into i18n

if (window.piskel_locale === undefined) {
	window.piskel_locale = 'en_us';
}
var i18n = window.piskel_locales[window.piskel_locale.toLowerCase()];

3. Use the i18n Object Where There Is Static Content

• In app.js it contains the controllers for all the tools used in Piskel app. We pass the i18n object to the controllers constructor
• In each of the controller, we replace the static text with an i18n key string
• For example, in ToolController, we pass the i18n to the SimplePen constructor then we change the value of this.helpText to i18n.simplePenDrawingTool which will return the correct string

ns.SimplePen = function(i18n) {
    this.toolId = 'tool-pen';
    this.helpText = i18n.simplePenDrawingTool();
    this.shortcut = pskl.service.keyboard.Shortcuts.TOOL.PEN;

    this.previousCol = null;
    this.previousRow = null;

    this.pixels = [];
};

4. HTML Templates

• There were some tools like changing the pen size and palette color that had their static text in HTML files

• The solution was to use their designated controller like PenSizeController or PaletteController and make a function that will generate the HTML based on a template given

• To Note

  • All these controllers:
    • SettingsController - GifExportController
    • PenSizeController - ZipExportController
    • PaletteController - ResizeController
    • Export Controller
  • They will all have a function ending with ...Dom_(). All these functions call other functions that will help generate HTML with i18n strings in them

• For example, in PenSizeController we have a function called createPenSizeDom_(). This function called in the PenSizeController constructor

ns.PenSizeController.prototype.createChangePenSize = function (i18n) {
    var templateValues = {
      title: i18n.penSizeChangeTitle() + '</br>' + i18n.penSizeChangeAvailableSizes(),
    };
    var templateId = 'change-pen-size-template';
    return pskl.utils.Template.fillInTemplate(templateId, templateValues);
  };

  /**
   * @private
   */
  ns.PenSizeController.prototype.createPenSizeDom_ = function (i18n) {
    $('#pen-size-container').html(this.createChangePenSize(i18n));
  };

• createPenSizeDom_() only has createChangePenSize(). This function has two variables templateValues and templateId. templateValues contain that values that will be replaced in the template. templateId is used to identify which template from misc-templates.html to use. We use this as arguments to fillInTemplate util function

/**
     * Takes in a templateId and values to replace the keys found in the template
     * @param {string} templateId - ID used to retrieve the correct template from misc-templates.html
     * @param {Object} templateValues - The values to fill in the template with.
     */
    fillInTemplate : function (templateId, templateValues) {
      var tpl = ns.Template.get(templateId);
      var templateWithValues = ns.Template.replace(tpl, templateValues);
      return templateWithValues;
    },

• The result then gets inserted in the drawing-tools.html in the div with the id="pen-size-container"

**5. Note About i18n Keys **

• This is the intention with how the keys were created.
  rotateTransformTool
  • The word rotate is the name of the tool
  • The word Transform is the directory it comes from
  • Then finish with Tool
• If a key has the word Descriptor in it for example rotateTransformToolDescriptorClockwiseRotation. It means that the tool has an extra description to give instructions about it or more info about the tool

Demo & Screenshots

Attached are screenshots and a video to show how it looks like with es_mx (Spanish, Mexico) translations

walkthrough.mp4

Follow Up Work

• Update Dashboard to use the new i18n version of Piskel.

[daynew]

Thank you for the thorough description of your work. This looks great!