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
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.
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>
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 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);
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 thetranslation 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
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");
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.
<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.
If you want to contribute to the project, you can open an issue or a pull request.