OpusCapita i18n

Synopsis

• Provides simple i18n mechanism for JS applications/modules.
• Provides data <-> string converters for
  • Dates
  • Numbers
  • Empty values (Strip to null converter)

Installation

Using npm

$ npm i --save @opuscapita/i18n

or

$ yarn add @opuscapita/i18n

Usage & API

I18nManager

Provides mechanism for internationalization according to the locale (with fallback), passed in the constructor. Also provides facade function for operating with converters, according to format patterns.

I18n manager creation

import { I18nManager } from '@opuscapita/i18n';

const localeFormattingInfo = {
  'en': {
    datePattern: 'dd/MM/yyyy',
    dateTimePattern: 'dd/MM/yyyy HH:mm:ss',
    integerPattern: '#,##0',
    numberPattern: '#,##0.00#######',
    numberDecimalSeparator: '.',
    numberGroupingSeparator: ',',
    numberGroupingSeparatorUse: true,
  }
};

let i18n = new I18nManager({
  locale: 'de-DE',         // current locale, by default 'en'
  fallbackLocale: 'en', // fallback locale, by default 'en'
  localeFormattingInfo,  // by default formatting information is set up for 'en' with values that you see in this sample
  overriddenTranslations, //key-value object of overridden translations
})                      

Deprecated constructor, please, don't use it anymore. It will be removed soon!

// obsolete constructor, please don't use it
let i18n = new I18nManager(
  'de-DE',                                // current locale
  [{                                   // default message bundles (use 'register' method for adding bundles)
    locales: ['en'],
    messages: {
      test: 'test message',
      format: 'min={min}, max={max}',
      subcomponent: {
        hint: 'nested hint'
      }
    },
  }],
  localeFormattingInfo,               // by default formatting information is set up for 'en' with values that you see in this sample
  'en'                                // fallback locale
  {
    'test': 'overridden translations'
  }                                   //object of overriden translations
);

Adding message bundles

Using flat structure (prefferable)

i18n.register('test_component', {
  'en': {
    'button.save.label': 'Save',
    'button.cancel.label': 'Cancel'
  },
  'de': {
    'button.cancel.label': 'Abbrechen'
  }
});

Using deep nested object structure

i18n.register('test_component', {
  'en': {
    button: {
      save: {
        label: 'Save'
      },
      cancel: {
        label:  'Cancel'
      }
    }
  },
  'de': {
    button: {
      cancel: {
        label:  'Abbrechen'
      }
    }
  }
});

Deprecated message bundle structure, please, don't use it anymore. It will be removed soon!

i18n.register('test_component', [
  {
    locales: ['en'],
    messages: {
      button: {
        save: {
          label: 'Save'
        },
        cancel: {
          label:  'Cancel'
        }
      }
    }
  },
  {
    locales: ['de'],
    messages: {
      button: {
        cancel: {
          label:  'Abbrechen'
        }
      }
    }
  },
]);

N.B. Messages defined in this way:

{
  'a.b.c': 'hi'
}

or another way

{
  a: {
    b: {
      c: 'hi'
    }
  }
}

are considered by i18n manager as equal and correspond to the same message key/path 'a.b.c'

Retrieving messages

Message is returned for current locale. If is not found then fallback locale logic is use. For example, if current locale is 'de-DE', then its fallback locale will be 'de', so message will be searched using 'de' locale. Final fallback language is the one that is passed in constructor (by default 'en').

// getting simple message
i18n.getMessage('test') // returns 'test message'

// getting message with arguments
i18n.getMessage('format', { min: 10, max: 100 }) // returns  'min=10, max=100'

// getting fallback message in default locale (en) in case of error (example de-DE -> de -> en)
i18n.getMessage('button.save.label') // returns 'Save'

// getting fallback message in root locale in case of error (example de-DE -> de)
i18n.getMessage('button.cancel.label') // returns 'de test message 2'

// getting fallback message key in case no values were found
i18n.getMessage('button.saveandnew.label') // returns 'button.saveandnew.label'

#### Data conversion

// Converter wrappers
i18n.formatDate(new Date(2001, 0, 10)) // returns '10/01/2001'
i18n.parseDate('10/01/2001').toISOString() // returns new Date(2001, 0, 10).toISOString()
i18n.formatDateTime(new Date(2001, 0, 10)) // returns '10/01/2001 00:00:00'

//format and parse numbers
i18n.formatNumber(10000) // returns '10,000'
i18n.parseNumber('10,000')// returns 10000

i18n.formatDecimalNumber(10000) // returns '10,000.00'
i18n.parseDecimalNumber('10,000.00') // returns 10000

// Wraps decimal number converter but allows the use of custom patterns
i18n.formatDecimalNumberWithPattern(10000, '#,##0.000000') // returns 10,000.000000

//format and parse big numbers
i18n.formatBigNumber('10000') // returns '10,000'
i18n.parseBigNumber('10,000')// returns '10000'

i18n.formatBigDecimalNumber('10000') // returns '10,000.00'
i18n.parseBigDecimalNumber('10,000.00') // returns '10000'

i18n.formatBigDecimalNumberWithPattern('10000', '#,##0.000000') // returns '10,000.000000'

// getting date format
i18n.dateFormat // returns 'dd/MM/yyyy'

Converters

Converter is a class that converts a value from its object representation to string one and reverse. All converters (Date, Number, StripToNull) implement the same interface that provides two methods valueToString and stringToValue.

Date Converter

import DateConverter from '@opuscapita/i18n/DateConverter';

let dc = new DateConverter(''MM/dd/yyyy'', 'en');
dc.valueToString(new Date(2001, 0, 15)) // returns '01/15/2001'
dc.stringToValue('01/15/2001') // returns new Date(2001, 0, 15)

NumberConverter

Format definition is similar to Java's DecimalFormat class, but exponent is not supported

import NumberConverter from '@opuscapita/i18n/NumberConverter';

let nc = new NumberConverter('#,##0.00', ',', '.'); // format, groupSep, decSep, decSepUseAlways = false
nc.valueToString(10000000) // returns '10,000,000.00'
nc.stringToValue('10,000.00') // returns 10000

BigNumberConverter

The converter format from and parse to only string values, because number package big numbers in JavaScript is not safety operation. Format definition is similar to Java's DecimalFormat class, but exponent is not supported

import BigNumberConverter from '@opuscapita/i18n/BigNumberConverter';

let nc = new BigNumberConverter('#,##0.00', ',', '.'); // format, groupSep, decSep, decSepUseAlways = false
nc.valueToString('9007199254740989.07') // returns '9,007,199,254,740,989.07'
nc.stringToValue('9,007,199,254,740,989.07') // returns '9007199254740989.07'

Strip to null converter

import StripToNullConverter from '@opuscapita/i18n/StripToNullConverter';

let stnc = new StripToNullConverter();
stnc.valueToString(null) // returns ''
converter.stringToValue('') // returns null

Migrate i18n-js to properties CLI

You can use i18n-js2properties CLI in your build process when package Grails plugins. The properties need to provide property keys and values for text localization service editor.

for example:

i18n-js2properties --source src/client/components/i18n --target ../plugin/grails-app/i18n/boilerplateEditor

If you want following translations in JavaScript frontend style

src/client/components/i18n/index.js
src/client/components/i18n/en.js
src/client/components/i18n/de.js

After that CLI will be generate following properties files

../plugin/grails-app/i18n/boilerplateEditor.properties
../plugin/grails-app/i18n/boilerplateEditor_en.properties
../plugin/grails-app/i18n/boilerplateEditor_de.properties

Contributors

| | Dmitry Divin | | :---: | :---: | | | Daniel Zhitomirsky | | | Alexey Sergeev |

License

OpusCapita i18n is licensed under the Apache License, Version 2.0. See LICENSE for the full license text.