Globalization

#Globalization

About This Page

Contains a proposal on how to approach Globalization for the Maqetta code base so that localized strings can be used instead of the current hard-coded English strings.

Basic Idea for javascript files

Creating Resource Bundles

Resource bundles will be written in AMD format. Each resource bundle pertaining to each locale will be in its specific locale folder. These locale folders will be contained in a folder named "nls" The basic format would look something like:

    define({
        root: {
            //fileContainingTheseStrings.js
            "selectDirectory":"Select Directory to link to",
            "parentFolder":"Parent Folder:"
        }
        // define properties for supported languages and variants
        // for each of these, include a translated bundle in a subdirectory by that name
        fr: true,
        zh: true
    })

Dojo Commands to Extract Localized Info

define(["dojo/i18n!davinci/subpath/nls/fileContainingTheseStrings"], function(resources){...});

Declares usage of localized resources.

The different localized strings contained in the object are available as properties of the object. ### Implementation Going off of [Dojo's i18n documentation quick start](http://dojotoolkit.org/reference-guide/quickstart/internationalization/resource-bundling.html#quickstart-internationalization-resource-bundling), the basic idea is to rference the localized resources as returned by ```define()``` or ```require()```. We then access the appropriate resources through the object. For objects using dijit/_TemplatedMixin, those properties may be mixed directly into ```this``` and substituted in the template using ```${}``` syntax.

If we were to want to localize the string "Select a theme" that appears when a user selects 'Switch Theme' in the toolbar, we would create a Resource Bundle like the following:

    define({
      //SelectThemeAction.js
      "selectTheme":"Select a theme"
    });

Since SelectThemeAction.js is located in davinci/actions, we would create an nls folder in the 'actions' folder and call our Resource Bundle actions.js. Within SelectThemeAction.js, we would include the following code at the top of the file to gain access to the newly created Resource Bundle:

    define(["davinci/actions/nls/actions", /*... other dependencies go here*/],
        function(actionsResources, ...){
            // body of module
        }
    );

Then within each function containing a hard-coded string, we need to create an object representing the localized resources. So in the case of selecting a theme, the function is run(), so within that function we references resources object (actionsResources). The different localized strings contained in that object are available as properties of the object. In place of the hard-coded string, we access the proper localized string (actionsResources.selectTheme).

    run: function(selection){
    var e = davinci.Workbench.getOpenEditor();
    var theme = e.getContext().getTheme();
    var ldojoVersion = e.getContext().getDojo().version.major +'.'+ e.getContext().getDojo().version.minor;

    this._themeChooser = new davinci.ui.widgets.ThemeSelection({'value':theme, workspaceOnly:false, dojoVersion: ldojoVersion });
    davinci.Workbench.showModal(this._themeChooser, actionsResources.selectTheme, "width:200px");
    dojo.connect(this._themeChooser, "onChange", this, "_changeTheme");	
    }

At runtime, it displays the string contained in the Resource Bundle. By convention, English is the default language and is provided as the "root", so it is not necessary to include an en or en-us folder with translations. However, if a Japanese translation is provided, the ja property would be assigned "true" in the base resource. For a user in Japan using the ja-jp locale, Dojo would retrieve the value contained in davinci/actions/nls/ja/actions.js rather than the one in davinci/actions/nls/actions.js.

Basic Idea for templates

Creating Resource Bundles

The same as for javascript files

Dojo Commands to Extract Localized Info

The same as above as well as dojo.mixin(this, theLanguageObject);

Implementation

If we were to want to localize the template newtheme.html, the Resource Bundle might look like:

    define({
    //newtheme.html
    "themeToClone":"Theme to clone",
    "newName":"New Name"
    });

Since newtheme.html is located in the davinci/ui, we'd add this to ui.js contained in davinci/ui/nls. Then we would replace the strings in the html file with the format ${resourceBundleStringName}. For example the first string in newtheme.html that needs to be localized is "Theme to clone." In newtheme.html it would look like (notice how it matches the name in the Resource Bundle):

    <div>
    <table>
    <tr>
    <td>${themeToClone}:</td><td> <div dojoType="davinci.ui.widgets.ThemeSelection" workspaceOnly="false" dojoAttachPoint = '_themeSelection'></div></td><td><div dojoAttachPoint='_error1'></div></td>
    </tr>
    ...

To connect everything together, we look at the corresponding javascript file (in this case NewTheme.js). As described in the section for javascript files, we first put the following dependency in the require call at the top of the file to gain access to the proper Resource Bundle:

    define([ ... "davinci/ui/nls/ui"], function( ..., uiResources){...});

Then we would include the function postMixInProperties as shown below. Within the function we combine the template and the strings in the Resource Bundle by invoking dojo.mixin(this, uiResources).

    ...
    dojo.declare([dijit._WidgetBase, dijit._TemplatedMixin], {
    postMixInProperties: function() {
       dojo.mixin(this, uiResources);
       this.inherited(arguments);
    },
    ...

In runtime, it displays the string contained in the Resource Bundle. English is the default, so it is not contained in an en or en-us folder. However, a user in Japan would use the ja-jp locale and see the value contained in davinci/actions/nls/ja/actions.js rather than the one in davinci/actions/nls/actions.js.

Widget Metadata

To be determined -- Most likely OpenAjax's syntax for message bundle files in xml or json

Maqetta Plugins

Globalization postponed until a later date.

Setting the Locale

While it was suggested not to decide this right now, two possible solutions are available here for setting a locale. Based on the information on that site, if no locale is specified then the default locale of the browser will be used, which is probably not a good approach in the long run.

Notes on Files

Width needs to be changed to work with different languages

• davinci/actions/SelectThemeAction.js
• davinci/actions/OpenThemeEditor.js
• davinci/ve/input/BorderContainerInput.js
• davinci/ve/input/DataGridInput.js

Yet to be globalized since they're still being worked on

• davinci/actions/saveAsWidget.js
• davinci/ui/SaveAsWidgetForm.js

Uses other files for globalization

• davinci/ve/palette -- common.js
• davinci/ve/prefs -- common.js

###Files that don't appear to be used yet

• Some of the files in davinci/ve/widgets (like Background.js and Border.js) don't seem to be used outside of this widgets folder. They look like they might one day be used in davinci/ve/views/SwitchingStyleView.js

Removed Files

• davinci/ve/actions/ChildActions.js
• davinci.review/WebContent.davinci.review/actions/ExplorerAction.js

Files with strings I cannot seem to find in the UI

• davinci/Workbench.js -- "Select Editor" -- commented out and edited
• davinci/Runtime.js -- "Careful! You are about to leave daVinci." -- globalized
• davinci/ve/Context.js -- "Careful! You are about to leave Maqetta." -- commented out
• Strings in ui/Panel.js-- strings aren't used, and they're noted as such though not commented out
• Strings in ve/HTMLVisualEditor.js -- commented out since the strings since no longer used

###Files that aren't used

• ui/templates/downloadSelected.html
• davinci/review/WebContent/davinci/review/actions/SubmitDraftAction.js - used in review_plugin.js but commented out

Localization Inventory (Incomplete)

I've marked things I believe I have completed -- unless I missed a string somewhere.

Maqetta palettes

• SwitchingStyleView.js -- the Properties palette
• Files in the widgets folder such as Background.js, Border.js, BorderRadius.js, etc. (didn't actually do Background.js, Border.js and BorderRadius.js in ve/widgets/ since they're currently not being used, but I did the others)

The palettes on the left and right side of the Maqetta user interface

Maqetta plugins (postponed)

ui_plugin.js, ve_plugin.js, review_plugin.js, themeEditor_plugin.js
These files contain the strings the user sees the most when using Maqetta.

Maqetta dialogs

• File dialogs in Resource.js
• Files containing alerts, prompts and dialogs such as newTheme.js, Runtime.js, StateActions.js, BorderContainerInput.js, etc.

###Widget metadata

• widgets.json
• *_oam.js files

###Widget metadata helper files

• Need to inventory *helper.js files in the metadata folders -- didn't find any

###Smart input helper files

• davinci.core/WebContent/davinci/ve/input/* - I see a string in DataGridInput.js, probably other files also have strings

###Theme metadata (e.g., davinci.dojo_1_7/WebContent/maqetta/themes/claro/*)

• *.theme files (e.g., claro.theme)
• *.json files (e.g., claro.json)

###Main file

• davinci.core/WebContent/pagedesigner.html might have a couple of strings

###Review and commenting (davinci.review project)

• davinci.review/WebContent/review.html might have a couple of strings
• davinci/review/actions/*.js
• davinci/review/widgets/*.js
• davinci/review/view/*.js
• davinci/review/*.js -- formHtml in Review.js
• davinci/review/util.js

###Mobile previewer code

• davinci.core/WebContent/preview.html might have a couple of strings
• davinci.core/WebContent/preview/singlepreview.js has a couple of strings

###Various files need to be totally replaced for localized versions

• All of the welcome.html files
• All of the welcome_to_maqetta.html files (e.g., davinci.core/WebContent/ve/resources/welcome_to_maqetta.html)
• davinci.core/WebContent/workspace/app.css
• Localized davinci.core/WebContent/samples/*.html? Probably not, but would be good to have things set up so that product teams could have localized versions if they so wanted

###Templates

• ui/templates/*.html
• davinci.review/WebContent/davinci/review/widgets/templates/*.html

###Need to study the davinci.core/WebContent/eclipse/* folder

• to see if anything there needs to be localized -- doesn't look like there is