i18x
v0.1.4
Published
Smart easy-to-use i18n library
Downloads
9
Maintainers
Readme
Smart i18n (i18x)
Smart easy-to-use i18n library
npm i i18x
or:
yarn add i18x
Usage
import I18n from 'i18x'
import messages from './messages.js' // your translation file. See below example: https://github.com/mirismaili/smart-i18n#example
const i18n = new I18n(messages)
const t = i18n.getTranslator('fa') // or easier: `const t = i18n.fa`
console.log(t`Hello`) // => سلام
Example
First create your translation file (we call it as messages.js
) file, based to this template:
export default {
en: {
// Meta-data-s won't be translated. They should start with `$`.
$dir: 'LTR',
$locale: 'en-US', // default to preset-name (here: 'en').
// can be used with unicode extension (e.g. 'en-US-u-ca-persian'). See:
// https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl
// $numberFormatOptions: { style: 'currency', currency: 'EUR' }, // optional
// Hello: "Hello", // doesn't need when key == value
},
fa: {
$dir: 'RTL',
$locale: 'fa-IR', // default to preset-name (here: 'fa'). can be used with unicode extension (-u-...)
// $dateTimeFormatOptions: { dateStyle: 'full', timeStyle: 'long' }, // optional
// punctuations:
',': '،', // comma
';': '؛', // semicolon
// single words:
Hello: 'سلام',
world: 'دنیا',
Human: 'انسان',
water: 'آب',
Earth: 'زمین',
Sun: 'خورشید',
Moon: 'ماه',
star: 'ستاره',
galaxy: 'کهکشان',
Venus: 'ناهید',
Mars: 'بهرام',
and: 'و',
or: 'یا',
// phrases and sentences:
'In the name of God': 'به نام خدا',
'the stars': 'ستارگان',
'is very nice': 'خیلی خوبه',
$numerical: {
0: '۰', // zero digit (next digits will automatically derived)
'.': '٫', // decimal separator
',': '٬', // thousands separator
},
},
$RTLs: { // all translations automatically considered TWO-DIRECTIONAL: { x: 'y' <=> y: 'x' }
'\u200E': '\u200F', // LRM ⇔ RLM // This special case will be defined automatically and can be omitted
// Each left-arrow that "its-unicode + 2" is the corresponding right-arrow, can be listed here:
// (notice TWO-DIRECTIONAL rule: left-arrow ⇔ right-arrow)
$arrows: [
'←',
'⇐',
],
},
}
Then create a new instance of I18n
class using that file and get your translators (t
):
import I18n from 'i18x'
import messages from './messages.js' // your translation file. See `example/messages.js`: https://github.com/mirismaili/smart-i18n/blob/main/example/messages.js.
const i18n = new I18n(messages)
const t = i18n['fa']
// simple translation:
console.log(t('Hello')) // سلام
console.log(t`Hello`) // سلام
const world = 'world'
console.log(t`Hello ${world}`) // سلام دنیا
// include numbers and dates:
console.log(t`${1 + 2}. Earth`) // ۳. زمین
console.log(t`1,234,567.890`) // ۱٬۲۳۴٬۵۶۷٫۸۹۰
console.log(t`Today: ${new Date()}`) // Today: ۱۴۰۰/۲/۲۶ // Note: "Today" hasn't been translated in `messages.js` file
// smart translation (detect translatable parts between a bigger string):
console.log(t`Hello, world`) // سلام، دنیا
// LTR <=> RTL
const LRM = '\u200E'
console.log(t`${LRM}Javascript is very nice!`) // Javascript خیلی خوبه!
// should be viewed in the right order and direction in real environments
See example.