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

Creating Resource Bundles

Resource bundles will be written in the JSON 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:

({
  //fileContainingTheseStrings.js
  "selectDirectory":"Select Directory to link to",
  "parentFolder":"Parent Folder:"
})

Dojo Commands to Extract Localized Info

dojo.require("dojo.i18n");

dojo.requireLocalization("directory.containing.nls.folder","resourceBundleName");
Declares usage of localized resources. The first argument is the directory structure containing the nls folder. The second argument is the name of the file within that directory that contains the localized strings.

dojo.i18n.getLocalization("directory.containing.nls.folder","resourceBundleName");
Returns a reference to the object representing the localized resources. The different localized strings contained in the object are available as properties of the object. The arguments match the arguments in dojo.requireLocalization().

Implementation

Going off of some of Adam's Dojo documentation found here, the basic idea is to assign the localized resources returned by dojo.i18n.getLocalization() to an object. We then access the appropriate resources through the object.

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:

({
  //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:

dojo.require("dojo.i18n");  
dojo.requireLocalization("davinci.actions", "actions");

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 create our language object (langObj). The different localized strings contained in the language object are available as properties of the object. In place of the hard-coded string, we access the proper localized string (langObj.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;

var langObj = dojo.i18n.getLocalization("davinci.actions", "actions");

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

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/action.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