localization routine and tests

Author: alexcjohnson

src/lib/index.js

@@ -106,6 +106,8 @@ lib.clearThrottle = throttleModule.clear;
 
 lib.getGraphDiv = require('./get_graph_div');
 
+lib._ = require('./localize');
+
 lib.notifier = require('./notifier');
 
 lib.filterUnique = require('./filter_unique');

src/lib/localize.js

@@ -0,0 +1,54 @@
+/**
+* Copyright 2012-2017, Plotly, Inc.
+* All rights reserved.
+*
+* This source code is licensed under the MIT license found in the
+* LICENSE file in the root directory of this source tree.
+*/
+
+
+'use strict';
+
+var Registry = require('../registry');
+
+/**
+ * localize: translate a string for the current locale
+ *
+ * @param {object} gd: the graphDiv for context
+ *  gd._context.locale determines the language (& optional region/country)
+ *  the dictionary for each locale may either be supplied in
+ *  gd._context.dictionaries or globally via Plotly.register
+ * @param {string} s: the string to translate
+ */
+module.exports = function localize(gd, s) {
+    var locale = gd._context.locale;
+
+    /*
+     * Priority of lookup:
+     *     contextDicts[locale],
+     *     registeredDicts[locale],
+     *     contextDicts[baseLocale], (if baseLocale is distinct)
+     *     registeredDicts[baseLocale]
+     * Return the first translation we find.
+     * This way if you have a regionalization you are allowed to specify
+     * only what's different from the base locale, everything else will
+     * fall back on the base.
+     */
+    for(var i = 0; i < 2; i++) {
+        var dicts = gd._context.dictionaries;
+        for(var j = 0; j < 2; j++) {
+            var dict = dicts[locale];
+            if(dict) {
+                var out = dict[s];
+                if(out) return out;
+            }
+            dicts = Registry.localeRegistry;
+        }
+
+        var baseLocale = locale.split('-')[0];
+        if(baseLocale === locale) break;
+        locale = baseLocale;
+    }
+
+    return s;
+};

src/plot_api/plot_config.js

@@ -126,5 +126,19 @@ module.exports = {
 
     // Set global transform to be applied to all traces with no
     // specification needed
-    globalTransforms: []
+    globalTransforms: [],
+
+    // Which localization should we use?
+    // Should be a string like 'en' or 'en-US'.
+    locale: 'en',
+
+    // Localization dictionaries
+    // Dictionaries can be provided either here (specific to one chart) or globally
+    // by registering them as modules.
+    // Here `dictionaries` should be an object of objects
+    // {'da': {'Reset axes': 'Nulstil aksler', ...}, ...}
+    // When looking for a translation we look at these dictionaries first, then
+    // the ones registered as modules. If those fail, we strip off any
+    // regionalization ('en-US' -> 'en') and try each again
+    dictionaries: {}
 };

src/plot_api/register.js

@@ -40,6 +40,10 @@ module.exports = function register(_modules) {
                 registerComponentModule(newModule);
                 break;
 
+            case 'locale':
+                Registry.registerLocale(newModule);
+                break;
+
             default:
                 throw new Error('Invalid module was attempted to be registered!');
         }

src/plot_api/validate.js

@@ -13,6 +13,7 @@
 var Lib = require('../lib');
 var Plots = require('../plots/plots');
 var PlotSchema = require('./plot_schema');
+var dfltConfig = require('./plot_config');
 
 var isPlainObject = Lib.isPlainObject;
 var isArray = Array.isArray;
@@ -40,9 +41,9 @@ var isArray = Array.isArray;
  *      error message (shown in console in logger config argument is enable)
  */
 module.exports = function valiate(data, layout) {
-    var schema = PlotSchema.get(),
-        errorList = [],
-        gd = {};
+    var schema = PlotSchema.get();
+    var errorList = [];
+    var gd = {_context: Lib.extendFlat({}, dfltConfig)};
 
     var dataIn, layoutIn;
 

src/registry.js

@@ -28,6 +28,7 @@ exports.componentsRegistry = {};
 exports.layoutArrayContainers = [];
 exports.layoutArrayRegexes = [];
 exports.traceLayoutAttributes = {};
+exports.localeRegistry = {};
 
 /**
  * register a module as the handler for a trace type
@@ -311,3 +312,39 @@ function getTraceType(traceType) {
     if(typeof traceType === 'object') traceType = traceType.type;
     return traceType;
 }
+
+/**
+ * Register a new locale dictionary
+ *
+ * @param {object} module
+ * @param {string} moduleType
+ *  should be 'locale' so that Plotly.register will forward to this function
+ * @param {string} module.name
+ *  the locale name. Should be a 2-digit language string ('en', 'de')
+ *  optionally with a country/region code ('en-GB', 'de-CH'). If a country
+ *  code is used but the base language locale has not yet been supplied,
+ *  we will use this locale for the base as well.
+ * @param {object} module.dictionary
+ *  the dictionary mapping input strings to localized strings
+ *  generally the keys should be the literal input strings, but
+ *  if default translations are provided you can use any string as a key.
+ */
+exports.registerLocale = function(_module) {
+    var locale = _module.name;
+    var baseLocale = locale.split('-')[0];
+
+    var newDict = _module.dictionary;
+
+    var locales = exports.localeRegistry;
+
+    // Should we use this dict for the base locale?
+    // In case we're overwriting a previous dict for this locale, check
+    // whether the base matches the full locale dict now. If we're not
+    // overwriting, locales[locale] is undefined so this just checks if
+    // baseLocale already had a dict or not.
+    if(baseLocale !== locale && locales[baseLocale] === locales[locale]) {
+        locales[baseLocale] = newDict;
+    }
+
+    locales[locale] = newDict;
+};

test/jasmine/assets/modebar_button.js

@@ -6,8 +6,14 @@ var modeBarButtons = require('../../../src/components/modebar/buttons');
 module.exports = function selectButton(modeBar, name) {
     var button = {};
 
+    var title = modeBarButtons[name].title;
+
+    if(typeof title === 'function') {
+        title = title(modeBar.graphInfo);
+    }
+
     var node = button.node = d3.select(modeBar.element)
-        .select('[data-title="' + modeBarButtons[name].title + '"]')
+        .select('[data-title="' + title + '"]')
         .node();
 
     button.click = function() {

test/jasmine/assets/supply_defaults.js

@@ -0,0 +1,14 @@
+'use strict';
+
+var Plots = require('@src/plots/plots');
+
+/**
+ * supplyDefaults that fills in necessary _context
+ */
+module.exports = function supplyDefaults(gd) {
+    if(!gd._context) gd._context = {};
+    if(!gd._context.locale) gd._context.locale = 'en';
+    if(!gd._context.dictionaries) gd._context.dictionaries = {};
+
+    Plots.supplyDefaults(gd);
+};

test/jasmine/tests/axes_test.js

@@ -14,6 +14,7 @@ var createGraphDiv = require('../assets/create_graph_div');
 var destroyGraphDiv = require('../assets/destroy_graph_div');
 var failTest = require('../assets/fail_test');
 var selectButton = require('../assets/modebar_button');
+var supplyDefaults = require('../assets/supply_defaults');
 
 
 describe('Test axes', function() {
@@ -49,7 +50,7 @@ describe('Test axes', function() {
                     type: 'date'
                 };
 
-            Plots.supplyDefaults(gd);
+            supplyDefaults(gd);
 
             Axes.swap(gd, [0]);
 
@@ -80,7 +81,7 @@ describe('Test axes', function() {
             expectedLayoutAfter.xaxis.type = 'linear';
             expectedLayoutAfter.yaxis.type = 'linear';
 
-            Plots.supplyDefaults(gd);
+            supplyDefaults(gd);
 
             Axes.swap(gd, [0]);
 
@@ -160,7 +161,7 @@ describe('Test axes', function() {
                     {x: 5, y: 0.5, xref: 'x', yref: 'paper'}
                 ];
 
-            Plots.supplyDefaults(gd);
+            supplyDefaults(gd);
 
             Axes.swap(gd, [0, 1]);
 
@@ -177,7 +178,8 @@ describe('Test axes', function() {
         beforeEach(function() {
             layoutOut = {
                 _has: Plots._hasPlotType,
-                _basePlotModules: []
+                _basePlotModules: [],
+                _dfltTitle: {x: 'x', y: 'y'}
             };
             fullData = [];
         });

test/jasmine/tests/bar_test.js

@@ -11,6 +11,7 @@ var createGraphDiv = require('../assets/create_graph_div');
 var destroyGraphDiv = require('../assets/destroy_graph_div');
 var fail = require('../assets/fail_test');
 var checkTicks = require('../assets/custom_assertions').checkTicks;
+var supplyAllDefaults = require('../assets/supply_defaults');
 
 var d3 = require('d3');
 
@@ -1520,10 +1521,11 @@ function mockBarPlot(dataWithoutTraceType, layout) {
     var gd = {
         data: dataWithTraceType,
         layout: layout || {},
-        calcdata: []
+        calcdata: [],
+        _context: {locale: 'en', dictionaries: {}}
     };
 
-    Plots.supplyDefaults(gd);
+    supplyAllDefaults(gd);
     Plots.doCalcdata(gd);
 
     var plotinfo = {

test/jasmine/tests/carpet_test.js

@@ -14,6 +14,8 @@ var fail = require('../assets/fail_test');
 var mouseEvent = require('../assets/mouse_event');
 var assertHoverLabelContent = require('../assets/custom_assertions').assertHoverLabelContent;
 
+var supplyAllDefaults = require('../assets/supply_defaults');
+
 describe('carpet supplyDefaults', function() {
     'use strict';
 
@@ -114,13 +116,13 @@ describe('carpet supplyDefaults', function() {
 describe('supplyDefaults visibility check', function() {
     it('does not hide empty subplots', function() {
         var gd = {data: [], layout: {xaxis: {}}};
-        Plots.supplyDefaults(gd);
+        supplyAllDefaults(gd);
         expect(gd._fullLayout.xaxis.visible).toBe(true);
     });
 
     it('does not hide axes with non-carpet traces', function() {
         var gd = {data: [{x: []}]};
-        Plots.supplyDefaults(gd);
+        supplyAllDefaults(gd);
         expect(gd._fullLayout.xaxis.visible).toBe(true);
     });
 
@@ -135,7 +137,7 @@ describe('supplyDefaults visibility check', function() {
             type: 'contourcarpet',
             z: [[1, 2, 3], [4, 5, 6]],
         }]};
-        Plots.supplyDefaults(gd);
+        supplyAllDefaults(gd);
         expect(gd._fullLayout.xaxis.visible).toBe(true);
     });
 
@@ -149,7 +151,7 @@ describe('supplyDefaults visibility check', function() {
             type: 'contourcarpet',
             z: [[1, 2, 3], [4, 5, 6]],
         }]};
-        Plots.supplyDefaults(gd);
+        supplyAllDefaults(gd);
         expect(gd._fullLayout.xaxis.visible).toBe(false);
     });
 
@@ -179,7 +181,7 @@ describe('supplyDefaults visibility check', function() {
             }]
         };
 
-        Plots.supplyDefaults(gd);
+        supplyAllDefaults(gd);
         expect(gd._fullLayout.xaxis.visible).toBe(true);
     });
 
@@ -209,7 +211,7 @@ describe('supplyDefaults visibility check', function() {
             }]
         };
 
-        Plots.supplyDefaults(gd);
+        supplyAllDefaults(gd);
         expect(gd._fullLayout.xaxis.visible).toBe(true);
     });
 });

test/jasmine/tests/choropleth_test.js

@@ -22,7 +22,8 @@ describe('Test choropleth', function() {
 
         var defaultColor = '#444',
             layout = {
-                font: Plots.layoutAttributes.font
+                font: Plots.layoutAttributes.font,
+                _dfltTitle: {colorbar: 'cb'}
             };
 
         beforeEach(function() {

test/jasmine/tests/colorscale_test.js

@@ -195,7 +195,8 @@ describe('Test colorscale:', function() {
     describe('handleDefaults (heatmap-like version)', function() {
         var handleDefaults = Colorscale.handleDefaults,
             layout = {
-                font: Plots.layoutAttributes.font
+                font: Plots.layoutAttributes.font,
+                _dfltTitle: {colorbar: 'cb'}
             },
             opts = {prefix: '', cLetter: 'z'};
         var traceIn, traceOut;
@@ -265,7 +266,8 @@ describe('Test colorscale:', function() {
     describe('handleDefaults (scatter-like version)', function() {
         var handleDefaults = Colorscale.handleDefaults,
             layout = {
-                font: Plots.layoutAttributes.font
+                font: Plots.layoutAttributes.font,
+                _dfltTitle: {colorbar: 'cb'}
             },
             opts = {prefix: 'marker.', cLetter: 'c'};
         var traceIn, traceOut;

test/jasmine/tests/contour_test.js

@@ -10,6 +10,7 @@ var fail = require('../assets/fail_test');
 var createGraphDiv = require('../assets/create_graph_div');
 var destroyGraphDiv = require('../assets/destroy_graph_div');
 var checkTicks = require('../assets/custom_assertions').checkTicks;
+var supplyAllDefaults = require('../assets/supply_defaults');
 
 
 describe('contour defaults', function() {
@@ -20,7 +21,8 @@ describe('contour defaults', function() {
 
     var defaultColor = '#444',
         layout = {
-            font: Plots.layoutAttributes.font
+            font: Plots.layoutAttributes.font,
+            _dfltTitle: {colorbar: 'cb'}
         };
 
     var supplyDefaults = Contour.supplyDefaults;
@@ -64,7 +66,7 @@ describe('contour defaults', function() {
             y: [1, 2],
             z: [[1, 2], [3, 4]]
         };
-        supplyDefaults(traceIn, traceOut, defaultColor, {calendar: 'islamic'});
+        supplyDefaults(traceIn, traceOut, defaultColor, Lib.extendFlat({calendar: 'islamic'}, layout));
 
         // we always fill calendar attributes, because it's hard to tell if
         // we're on a date axis at this point.
@@ -80,7 +82,7 @@ describe('contour defaults', function() {
             xcalendar: 'coptic',
             ycalendar: 'ethiopian'
         };
-        supplyDefaults(traceIn, traceOut, defaultColor, {calendar: 'islamic'});
+        supplyDefaults(traceIn, traceOut, defaultColor, Lib.extendFlat({calendar: 'islamic'}, layout));
 
         // we always fill calendar attributes, because it's hard to tell if
         // we're on a date axis at this point.
@@ -182,7 +184,7 @@ describe('contour calc', function() {
             trace = Lib.extendFlat({}, base, opts),
             gd = { data: [trace] };
 
-        Plots.supplyDefaults(gd);
+        supplyAllDefaults(gd);
         var fullTrace = gd._fullData[0];
 
         var out = Contour.calc(gd, fullTrace)[0];