Simple i18n library for Browser and nodejs environments.
npm install @webstory/inline-i18n
Safely wrap your strings with i18n
function without modification.
/// Example 1
import i18n from '@webstory/inline-i18n';
// import { i18n } from '@webstory/inline-i18n'; // Alternate import
console.log(i18n('Hello, world!')); // Hello, world!
This library will automatically detect the user's preferred language if this is running in a browser environment.
`<language_code>:your_string`
`<language_code>-<region_code>:your_string`
Valid:
"en:Hello, world!"
,"ko:안녕, 세계!"
"en:fr:ko:ja"
(multiple colons are allowed - use only the first one)"en-US:Hello, world!"
(language code with region)
Not valid:
"Hello, world!"
(no language code)"␣ko:안녕, 세계!"
(space before language code)"ko␣:안녕, 세계!"
(space between language code and colon)"EN:Hello, world!"
(uppercase language code)"GB:Hello, world!"
(region code only)"en-gb:Hello, UK!"
(lowercase region code)
/// Example 2
import i18n from '@webstory/inline-i18n';
console.log(navigator.languages); // ['ko-KR', 'ko', 'en-US', 'en']
console.log(i18n(['en:Hello, world!','ko:안녕, 세계!'])); // 안녕, 세계!
console.log(i18n(['en:fr:ko:ja'])); // fr:ko:ja (Language code is trimmed)
You will get warning if invalid syntax is given.
import i18n from '@webstory/inline-i18n';
// Will get warning on console
console.log(i18n(['en:Hello, world!','안녕, 세계!']));
// prints "Hello, world!"
// because '안녕, 세계!' has no language code.
To set language manually, you can use i18nContext.setPriority
function.
/// Example 3
import i18n from '@webstory/inline-i18n';
// Set Language priority list
// Warning: This will override the default language detection
// And this change will be applied globally
i18n.setPriority(['en', 'ko']);
console.log(i18n(['en:Hello, world!','ko:안녕, 세계!'])); // Hello, world!
Priority set with region code
/// Example 4
import i18n from '@webstory/inline-i18n';
i18n.setPriority(['en-GB', 'en-US', 'en']);
console.log(i18n(['en:Hello, world!','ko:안녕, 세계!'])); // Hello, world!
console.log(i18n(['en-GB:Hello, UK!','en:Hello World!'])); // Hello, UK!
If no matching language is found, the first item will be returned.
/// Example 5
import i18n from '@webstory/inline-i18n';
i18n.setPriority(['zh']);
console.log(i18n(['en:Hello, world!','ko:안녕, 세계!', "ru:Привет, мир!"])); // Hello, world!
Could be useful when your application have separated pages which have country-specific contents.
/// Example 6
import { I18NContext } from '@webstory/inline-i18n';
const i18nEn = new I18NContext(['en', 'ko']);
const i18nKo = new I18NContext(['ko', 'en']);
console.log(i18nEn.t(['en:Hello, world!','ko:안녕, 세계!'])); // Hello, world!
console.log(i18nKo.t(['en:Hello, world!','ko:안녕, 세계!'])); // 안녕, 세계!
You can use I18NDictionary
type to define your dictionary.
This is mostly equal to { [key: string]: string }
type. Therefore you can use a plain object as a dictionary.
/// Example 7
import type { I18NDictionary } from '@webstory/inline-i18n';
import { i18n } from '@webstory/inline-i18n';
const strDict: I18NDictionary = {
en: "Hello, World!",
es: "¡Hola, Mundo!",
fr: "Bonjour, le monde!",
de: "Hallo, Welt!",
it: "Ciao, mondo!",
pt: "Olá, mundo!",
ru: "Привет, мир!",
zh: "你好,世界!",
ja: "こんにちは、世界!",
ko: "안녕, 세상!",
};
i18n.setPriority(['en', 'ko']); // Optional; follows `navigator.languages` by default
console.log(i18n(strDict)); // Hello, World!
💥EXPERIMENTAL💥 You can use 'popularity' option on the setPriority()
function.
/// Example 8
import i18n from '@webstory/inline-i18n';
i18n.setPriority('popularity');
console.log(i18n(['uz:Salom Dunyo!','ru:Привет, мир!'])); // Привет, мир!
Returns the best matching string from the given list of strings.
Sets the priority list of languages. This will override the default language detection.
Returns the current priority list of languages.
Unlike i18n.getLanguage()
, this won't trim the region code.
Result can be 'popularity' or empty array.
Returns the first language code of the current priority list.
This will trim the region code if it exists.
Will throw an error if the priority list is empty.
Creates a new I18NContext instance with the given priority list. If no priority list is given, it will follow the default language detection.
Returns the best matching string from the given list of strings.
Same as i18n()
function, but this will use the priority list of the context.
Same as above, but this will only affect the context.
Same as above, but this will only affect the context.
Same as above, but this will only affect the context.
An array of language codes sorted by popularity. Full list is available in the constants.ts file.
A regular expression to match the i18n string format. Useful for debug.
/^<language_code>(-<region_code)?:.+$/
actual regex:/^[a-z]{2}(-[A-Z]{2,3})?:.+$/
A regular expression to match the language code format. Useful for debug.
/^[a-z]{2}(-[A-Z]{2,3})?$/
Full type definitions are available in the types.ts file.
type I18NDictionary = { [key: string]: string };
type I18NOption = {
priority?: string[] | 'popularity';
};
This library uses navigator.languages
to detect the user's preferred language.
Check caniuse.com - navigator.languages for more information.
MIT