Skip to content

eartharoid/i18n

main
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
src
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

i18n

Simple and lightweight message localisation for JavaScript projects.

Installation

  • pnpm add @eartharoid/i18n or
  • yarn add @eartharoid/i18n or
  • npm i @eartharoid/i18n

Usage

const I18n = require('@eartharoid/i18n');
const i18n = new I18n('english', {
	english: {
		example: 'Hello, world'
	},
	russian: {
		example: 'https://www.youtube.com/watch?v=bwnksI2ZoJI'
	}
});

// note: you should check if the locale exists in i18n.locales first
const messages = i18n.getLocale('russian'); // get the locale
console.log(messages('example')); // -> https://www.youtube.com/watch?v=bwnksI2ZoJI

// this code does exactly the same
console.log(i18n.getMessage('russian', 'example'));

Placeholders

i18n supports both positional and named placeholders.

{ // a locale object
	"positional": {
		"strings": "I like %s", 
		"numbers": "%d %s %d = %d"
	},
	"named": {
		"example1": "Hi, I'm {name} and I am from {location}",
		"example2": "Hi, I'm {person.name} and I am from {person.location}"
	}
}

Also note that messages and named placeholders can be nested

messages('positional.strings', 'chocolate'); // I like chocolate

messages('positional.numbers', 5, '+', 5, 10); // 5 + 5 = 10

messages('named.example1', {
	name: 'Someone',
	location: 'Somewhere'
}); // Hi, I'm Someone and I am from Somewhere

messages('named.example2', {
	person: {
		name: 'Someone',
		location: 'Somewhere'
	}
}); // Hi, I'm Someone and I am from Somewhere

Pluralisation

i18n supports basic pluralisation. If the message is an array, the first placeholder value will be "eaten" (consumed) and the correct message will be returned.

[
	"1",
	"anything else"
]

or

[
	"0",
	"1",
	"anything else"
]
{ // a locale object
	"example1": [
		"You only have one %s",
		"You have %d %ss"
	],
	"example2": [
		"You don't have any {item}s",
		"You only have one {item}",
		"You have {number} {item}s"
	]
}
messages('example1', 1, 1, 'item')
messages('example2', 0, {
	number: 0,
	item: 'car'
})

API

new I18n(default_locale, locales)

Create a new I18n instance

  • default_locale - the name of the default locale
  • locales - an object of localised messages

I18n#default_locale

The name of the default locale

I18n#locales

An array of the names of the locales you created

I18n#getAllMessages(message, ...args)

Get a message in all locales

  • message - dot notation string for the message
  • ...args - placeholders/pluralisation

I18n#getLocale(locale)

Get a locale

  • locale - locale name

Returns a function which calls I18n#getMessage using the given locale name (or the default).

I18n#getMessage(locale, message, ...args)

Get a message from a specific locale

  • locale - locale name
  • message - dot notation string for the message
  • ...args - placeholders/pluralisation

I18n#getMessages(locales, message, ...args)

Get a message from multiple locales

  • locales - array of locale names
  • message - dot notation string for the message
  • ...args - placeholders/pluralisation

Support

Discord support server

Donate

ko-fi

License

MIT license.

© 2022 Isaac Saunders