intl-ts is an i18n (internationalization) library for TypeScript. The package is compiled in ES2015 and so can also be used by JavaScript applications, but may require a Babel translation to be used with browsers. Its main features are:
- Type safe: using a wrong message name or the wrong type for the parameters will be checked at compile time. If your IDE allow it, you may even have completion for message names.
- Mutable or immutable: the library can be used in an immutable way (good for most state-aware framework, like React/Redux), or in a mutable way (for better performance).
- MobX integration: if you are using MobX, the
$preferencesproperty of theIntlobject will automatically become observable, allowing, for example,Reactcomponents to automatically refresh when chosen language changes. - Agnostic: can be used both at server (NodeJS) or browser side.
If you were using a previous version of the library, you may be interested by the migration guide
Documents, messages, code (including variable names and comments), are in English.
Anyway, because Slune is French firm, all documents and important messages must also be provided in French. Other translations are welcome.
🇫🇷 Une version française de ce document se trouve ici.
Installation is done using npm install command:
$ npm install --save intl-ts- Create your language strings (messages):
// English version — default
const en = createMessages({
$: 'English',
welcome: 'Welcome here!',
hello: (name: string) => `Hello ${name}`,
showElementCount: (count: number) => {
switch (count) {
case 0: {
return 'There are no elements'
}
case 1: {
return 'There is one element'
}
default: {
return `There are ${count} elements`
}
}
},
})
// Type describing messages
type langType = typeof en
// French version — full
const fr = createMessages<langType>({
$: 'Français',
welcome: 'Bienvenue ici !',
hello: (name: string) => `Bonjour ${name}`,
showElementCount: (count: number) => {
switch (count) {
case 0: {
return 'Il n’y a pas d’éléments'
}
case 1: {
return 'Il y a un élément'
}
default: {
return `Il y a ${count} elements`
}
}
},
})
// Canada french version — partial
const fr_ca = createMessages<PartialMessages<langType>>({
$: 'Français (Canada)',
welcome: 'Bienvenue icitte !',
})
// Esperanto version — partial
const eo = createMessages<PartialMessages<langType>>({
$: 'Esperanto',
welcome: 'Bonvenon ĉi-tie!',
hello: (name: string) => `Saluton ${name}`,
})The function createMessages is actually an identity function and is therefore not mandatory. Its sole purpose is to allow TypeScript to check the type of the given messages.
Note that the message names must not contain one of the keyword of the Intl API.
- Create the corresponding language map:
// Direct creation
const languageMap = new LanguageMap({
default: en,
en: 'default',
fr,
fr_ca,
eo,
})
// Dynamic creation
const languageMap = new LanguageMap(en, 'en').merge({ fr, fr_ca }).merge({ eo })Note that you should only use lowercase letters, digits and underscores as keys in language maps, because language codes will be formatted this way by the Intl class.
- Create the internationalization object, and use it!
const lang = new Intl<langType>(languageMap, ['eo', 'fr-CA'])
lang.welcome() // 'Bonvenon ĉi-tie!'
lang.showElementCount(0) // 'Il n’y a pas d’éléments' — Compilation check that 0 is of type numberObject states will never change except:
- Internal string representation of the
LanguageMap(because of lazy initialization), - if you choose to update the language preferences with
Intl.$changePreferences, but you can choose to update them by cloning initial object using the copy constructor.
A new object is created when calling LanguageMap.merge().
Even though we cannot guarantee a response time, please feel free to file an issue if you have any question or problem using the package.
Pull Requests are welcome. You can, of course, submit corrections or improvements for code, but do not hesitate to also improve documentation, even for small spell or grammar errors.