Implementing localization

The DataEntry library defines an interface to implement localization of error messages:

Method	Description
t(string key, object options) -> string	Translates an error key name to a culture specific error message
lookup(string key) -> bool	Returns a value indicating whether a localized error message exists for a given key

// example implementation of localizer interface:
const reg = {
  "required": "The field requires a value",
  "minLength": "The field value is too short"
};

DataEntry.configure({
  localizer: {
    t: function (key) {
      return reg[key] || key;
    },
    lookup: function (key) {
      return reg.hasOwnProperty(key);
    }
  }
})

Using libraries for localization

Following examples show how to integrate a library like one of:

• I.js
• i18n-js

The first library (done by the same author of DataEntry) should be used only if advanced features like parsing of dates, support for currencies, etc., are not needed in other parts of the application. The second should be used if advanced localization features are required in other parts of the application.

The DataEntry library itself only requires support for scoped translations.

Example with I.js

This example shows how to implement localization using I.js. First, load the i.js library, in the desired way. In this example, ES6 import syntax is used:

Then, make sure that its regional object is extended with the required texts and cultures:

import _ from "lodash"  // installed using npm install lodash
import I from "ilocale" // installed using npm install ilocale

// extend regional object with translations for English language:
_.extend(I.regional, {
  
  "en": {
    "errors": {
      "required": "The field cannot be empty",
      "selectValue": "Please select a value",
      "notInteger": "The value is not a valid integer",
      "minValue": "The minimum value is {{min}}",
      "maxValue": "The maximum value is {{max}}",
      "minLength": "The minimum value length is {{length}}",
      "maxLength": "The maximum value length is {{length}}",
      "invalidValue": "The value is invalid",
      "canContainOnlyLetters": "The field can contain only letters",
      "canContainOnlyDigits": "The field can contain only digits",
      "mustBeChecked": "This must be checked"
    }
  }
});

Configure the DataEntry to use I:

import DataEntry from "dataentry"
import I from "ilocale"

DataEntry.configure({
  localizer: {
    t: function (key, options) {
      return I.t("errors." + key, options);
    },
    lookup: function (key) {
      return I.lookup("errors." + key);
    }
  }
})

Then, an error message for a validation rule defined this way:

      schema: {
        foo: [{
          name: "minLength",
          length: 5
        }]
      }

Would be translated to: The minimum value length is 5.

Example with i18n-js

This example shows how to implement localization using i18n-js. First, load the i18n-js library, in the desired way, for example:

  <script src="scripts/libs/i18n.js"></script>
  <script>
    I18n.defaultLocale = "en";
    I18n.locale = "en";
  </script>

Then, make sure that its translations object is extended with the required texts and cultures: (Example using Lodash: _ global variable)

_.extend(I18n.translations, {
  
  "en": {
    "errors": {
      "required": "The field cannot be empty",
      "selectValue": "Please select a value",
      "notInteger": "The value is not a valid integer",
      "minValue": "The minimum value is {{min}}",
      "maxValue": "The maximum value is {{max}}",
      "invalidValue": "The value is invalid",
      "canContainOnlyLetters": "The field can contain only letters",
      "canContainOnlyDigits": "The field can contain only digits",
      "mustBeChecked": "This must be checked"
    }
  }
});

Configure DataEntry to use I18n:

DataEntry.configure({
  localizer: {
    t: function (key, options) {
      return I18n.t("errors." + key, options);
    },
    lookup: function (key) {
      return I18n.lookup("errors." + key);
    }
  }
})

Fields specific error messages

Error messages can also be specified when defining DataEntry schema. In the following example, taken from the unit tests of the library, when a value for foo is missing, the error message: "A foo is required" is used; while for key field the error message: "A key is required" is used.

var data = {
  foo: null,
  key: ""
};

var a = new DataEntry({
  schema: {
    foo: [{ name: "required", message: "A foo is required" }],
    key: [{ name: "required", message: "A key is required" }]
  },
  marker: new TestMarker(data),
  harvester: new TestHarvester(data)
})

Message can also be a function returning a message:

var a = new DataEntry({
  schema: {
    foo: [{ 
      name: "required", 
      message: function () {
        return "A foo is required";
      }
    }],
    key: [{ 
      name: "required", 
      message: () => {
        return "A key is required"
      }
    }]
  },
  marker: new TestMarker(data),
  harvester: new TestHarvester(data)
})

In such case, the message function is called with field and value parameters.

Note: error messages defined this way bypass the localizer object.