two-mi18n

Minimalist Javascript library for internationalization in only two methods. Too minimalist.

Two Mi18n is a Javascript library for translating websites directly on the client. The goal of this library is to provide the easiest way to translate any website.

• Minimalist and easy to use: Only two methods
• Lightweight: ~1.6 KB minified
• Client-side oriented

Inspiration

I was searching for a simple way to translate my website. I have found some libraries but they were too complicated for my needs. So I decided to build my own.

I had the idea of a client-side i18n library in mind, then found simple-translator that had the same idea but 3 years before. But I wanted something more minimalist. So I take inspiration from Apline.js for its minimalist approach.

Getting started

Installation

Since it is Client-side oriented, the best way to use it is to call the CDN with this script tag:

<script
	defer
	src="https://unpkg.com/two-mi18n@latest/dist/TwoMi18n.umd.js"
></script>

Usage

The translation object

The translation object is a simple Javascript object that contains the translations. Its keys are the language keys and its values are objects that contain the translations with keys and values.

The translation object must have a default key that contains the default language. The default language value must exist in the translation object

const translations = {
	default: "en",
	en: {
		hello: "Hello",
		world: "World",
	},
	fr: {
		hello: "Bonjour",
		world: "Monde",
	},
};

The TwoMi18n object

The TwoMi18n object is the main object of the library. It contains the two methods of the library.

The translation object will be validated by the TwoMi18n constructor. If the translation object is not valid, an error will be thrown.

const twoMi18n = new TwoMi18n(translations);

Translate in Javascript

The translate method is the method that will translate a single string. It takes two arguments:

• key: The translation key.
• lang: The language to translate to from the translation object.

twoMi18n.translate("hello", "fr"); // Bonjour

You can use any type of language code, are even create new ones.

If you pass a language that is not in the translation object, it will try the first 2 letters. This behavior is useful if you want to specify language variations depending on the location. For example en-GB.

const translations = {
	default: "en",
	en: {
		hello: "Hello",
		color: "Color",
	},
	en-GB: {
		hello: "Hello",
		color: "Colour",
	},
};

twoMi18n.translate("color", "en"); // Color
twoMi18n.translate("colour", "en-GB"); // Colour

Now if you want to get a translation for a country not defined in the translation object, like en-US. It will try to match the two first letters.

twoMi18n.translate("Color", "en-US"); // Color
//Fallback to the first two letters. Here "en".

If a not-defined variable that doesn't fall back with its two first letters is passed in the param, it will take the value from the default.

twoMi18n.translate("color", "it"); // Color

Translate in HTML

Add the data-twomi18n attribute to the elements that need to be translated in the HTML. The value of the attribute is the translation key.

<h1 data-twomi18n="hello"></h1>

The translateHTML method is the method that will translate all the elements with the data-twomi18n attribute.

It takes one argument:

• lang: The language to translate to

twoMi18n.translateHTML("fr");

Translate HTML attributes

The translateHTML method can also translate HTML attributes. Add the attribute name after the translation key between brackets to specify the attribute to translate.

<input type="text" data-twomi18n="hello[placeholder]"></input>

You can translate multiple attributes by separating them with a space.

<input
    type="text"
    data-twomi18n="world hello[placeholder] world[title]"
></input>

Note: When the attribute is not specified, the innerText attribute is used.

Example

<header>
	<h1 data-twomi18n="hello"></h1>
    <input
        type="text"
        data-twomi18n="world hello[placeholder] world[title]"
    ></input>
</header>

<script
	defer
	src="https://unpkg.com/two-mi18n@latest/dist/TwoMi18n.umd.js"
></script>

<script defer>
	const translations = {
		default: "en",
		en: {
			hello: "Hello",
			world: "World",
		},
		fr: {
			hello: "Bonjour",
			world: "Monde",
		},
	};

	const twoMi18n = new TwoMi18n(translations);

	twoMi18n.translateHTML("fr");
</script>

See a full working example:

See the full documentation on twomi18n.nicolasrenault.com.

Contribute

If you want to contribute to the project, you can open an issue or a pull request.

License

MIT