@domoinc/i18n

i18n

Light-weight Internationalization library for client-side projects.

documentation

What is i18n?

i18n is the short-hand for the word "internationalization". There are exactly 18 letters between the first and last letter of the word, hence i18n. Likewise, L10n is the short-hand for the word "Localization".

i18n should always be referenced with a lowercase ibecause a capital I looks too much like a 1 (one).

L10n should always be referenced with a capital Lbecause a lowercase l looks too much like a 1 (one).

The term 'internationalization' or 'i10n' refers to the master process while 'localization' refers to a specific implementation of internationalization. In other words, i18n is the recipe and L10n is the cookies.

Philosophy

This library has been developed with the following requirements in mind:

• IE9+ Browser Compatibility - We've committed to support any major browser released after IE9.
• No Dependancies - Everything is written in vanilla javascript with exception of dates (we're using moment.js).
• Don't Reinvent the Wheel - We're using we'll documented, native JS methods such as toLocaleString() as much as possible.

Supported Use Cases

• Number Formatting - ex. 1000 --> 1,000
• Currency Formatting - ex. 1000.35 --> $1,000.35
• Percentage Formatting - ex 0.35 --> 35%
• Summary Numbers - ex 1242.4 > 1.242K
• String Translations - ex. "Hello World" --> "Hallo Welt"
• Image Switching

What about dates?

I've not yet implemented a solution for dates. In accordance with the 'don't reinvent the wheel' philosophy, I figure that any time we're dealing with dates, we're probably going to be pulling in a date library to help. In my experience, nobody likes dealing with javascript dates directly . Most (good) date libraries have internationalization built in. For more info:

• Moment.js
• Date.js

Usage

The i18n object will be a global variable that you can use to help you localize your project. More documentation coming soon.

Methods

// L for language. This is the current language getter/setter. 
i18n.l('en-us')

// C for currency. This is the current currency getter/setter. 
i18n.c('USD')

// TODO: Gets language setting from server, its the most accurate place to get it. 
i18n.getLanguage()

// TODO: Gets currency setting from server.
i18n.getCurrency()

// Truncates a string to a specified number of characters. 
i18n.trunc('string', 5, true)

// Fetches the translation file and then executes a callback function.
i18n.init(callback)

// T for translate. This will return a specified translation.
i18n.t('dot.notation')

// Returns a summarized number like '152.3K'.
i18n.summaryNumber(number)

// Return the number and magnitude of number as an object.
i18n.summaryNumberToObject(number)

// Converts summary number back to actual number.
i18n.reverseSummaryNumber('123K')

Variables

// the current currency symbol
i18n.$ = "$";

/******************************************
I STRONGLY SUGGEST YOU DON'T USE THESE:
******************************************/
// the current language code
i18n.defaultLanguage

// the current currency code
i18n.defaultCurrency

Shim toLocaleString()

The toLocaleString() is a very powerful method on the number prototype in JavaScript. The only bad thing is that it's not fully implemented in Safari. I've created a shim (that follows the documented spec perfectly) so that it will work on any browser. Please, read the docs and learn how to incorporate this into your projects.

MDN - toLocaleString()

Notes

What works

Basically, everything except the translation piece. Getting the user's settings from product and/or server are also not ready yet so you'll have to hard code those values for now.

Needed Product Features

1. Get locale settings exposed from product.
2. A place to host language files. This probably won't happen until we get Mason v1.

TODO

1. Finish the shim.
2. Test, Test, and Retest.