Translator Documentation

Builder supports displaying the GUI in multiple languages, and allows the user to choose which language they want to use. By default, Builder picks the language it has available that best matches the locale set. That is, it will first see if it has a translation for the exact locale, then fall back to a translation for the language, and then finally fall back to English.

So, for example, if the locale is de-CH (German-Switzerland), it would first look for a German/Swiss-specific translation. Since none is available, it would fall back to just de, which is available. Or if the locale is it-CH (Italian-Switzerland), it would fall back to it (generic Italian) and then finally to en (generic English).

To add a new language pack to Builder, you can go two routes. You can create a plugin that adds the language pack, or you can fork the se-builder project, add in your new language, and then issue a pull request to have the new language included.

The advantage of the former is that you can start using and distributing the new translation immediately, while with the latter, you will have to wait until the next point release of Builder. If you go down the former route, we heavily encourage you to also submit the translation for direct inclusion!

How to write a language pack

The best way to do this is to pick an existing pack from seleniumbuilder/chrome/content/html/js/builder/i18n. The en.js pack is probably easiest for reference, but it doesn't have mappings for the names of steps, so you may also need to refer to de.js or fr.js. The latter is on track for being the most complete translation, including translation of all the step type documentation.

Duplicate the pack you're going to work from, and rename it as the language you are targeting, for example es.js for Spanish. Then, change the name and code at the start of the file to match this. For example:

var m = {};
builder.translate.addLocale({'name':'es', 'title': "Español", 'mapping': m});

Then, translate all the mappings in the file. For example, the line

m.cancel = "Cancel";

would become

m.cancel = "Cancelar";

(Apologies for any bad examples in on this page, I'm afraid I'm working off Google translate, not an actual working knowledge of the Spanish language.)

The meaning of the terms in brackets

The {0}, {1} and {2} terms in the translation strings are places where text is substituted in by Builder. For example, in

m.save_as_X_to_Y = "Save as {0} to {1}";

{0} is substituted with the name of the format the file will be saved as, and {1} with the path it will be saved to. For example "Save as Java to /Users/zar/Desktop/test.java". This allows you to rearrange the order in which these terms appear to better suit the syntax of your target language.

How to add the translation using a plugin

Once you have your new translation file, you will want to add it to Builder.

To do so from a plugin, simply create a plugin that loads in your translation file. In the case of a Spanish translation, this would consist of a directory called spanish_translation containing es.js and a header.json file looking something like this:

{
  "headerVersion": 1,
  "pluginVersion": "1.0",
  "builderMinVersion": "2.0.1",
  "builderMaxVersion": "2.0.*",
  "identifier": "spanish_translation",
  "name": "Spanish Language Pack",
  "description": "Adds Spanish translation for the Builder UI.",
  "siteUrl": "http://www.yourwebsite.com/homepage_of_spanish_plugin/",
  "load": [
    "es.js"
  ]
}

(See more information about plugins.)

You can then copy this directory into <your Firefox profile directory>/SeBuilder/plugins to make it available to Builder. Once you're satisfied with the translation, submit the plugin to us for inclusion in the plugins list.

How to include the translation directly in Builder

Alternatively, if you've set up Builder for development, put your file into seleniumbuilder/chrome/content/html/js/builder/i18n, next to en.js et al, and insert the line

"builder/i18n/es.js",

into seleniumbuilder/chrome/content/html/js/builder/loader.js, just after the other lines loading in language packs. Once you're satisfied with the translation, you can issue a pull request or just email us the translation file, and it will be included in the next version of Builder.