nano-i18n

nano-i18n

Tiny experimental i18n library for JavaScript using tagged template literals.

I'm starting small and evolving as the need arises.

Installation

Try it out

You can try out the API on RunKit without installing the library.

As a Node.js module

Install the library using npm or yarn:

npm install nano-i18n

yarn add nano-i18n

Using unpkg

You can load the library through a <script> tag using unpkg.com:

<script src='https://unpkg.com/nano-i18n'></script>

Usage

import { load, k, v, t } from 'nano-i18n';

// 1. Load some translations

// Simple replacement
load(k`Hello, ${'World'}!`, v`Salut, ${0}!`);

// Swap the order of values in the translation
load(k`My name is ${'mine'}, yours is ${'yours'}`, v`Your name is ${1}, mine is ${0}`);

// 2. Translate some messages
console.log(t`Hello, ${'Dan'}!`);
// => "Salut, Dan!"

console.log(t`My name is ${'Dan'}, yours is ${'Alex'}`);
// => "Your name is Alex, mine is Dan"

API reference

Managing translations

§ load(key: string, value: string | function)

Set up a translation:

import { load } from 'nano-i18n';

load(k`Hello, ${'World'}!`, v`Salut, ${0}!`);

You can also add a batch of translations:

import { load } from 'nano-i18n';

let translations = {};
translations[k`Hello, ${'World'}!`] = v`Salut, ${0}!`;
translations[k`My name is ${'name'}`] = v`Numele meu este ${0}`;

load(translations);

Or using the computed property names syntax:

import { load } from 'nano-i18n';

load({
	[k`Hello, ${'World'}!`]: v`Salut, ${0}!`,
	[k`My name is ${'name'}`]: v`Numele meu este ${0}`
});

Or skipping the k literal tag altogether and using a string key directly:

import { load } from 'nano-i18n';

load('Hello, {}!', v`Salut, ${0}!`);

You can also skip the v literal tag and send a simple string translation:

import { load } from 'nano-i18n';

load('Hello, World!', 'Salut, lume!');

§ clear()

Clears all the translations:

import { clear } from 'nano-i18n';

clear();

§ config(options: object)

Configures the library. Available options:

log (Number, default 0)

The log level for the library. Possible values:

• 0 disables logging
• 1 logs a warning in the console on a missing translation
• 2 throws an error when encountering a missing translation

placeholder (String, default {})

The string to use as placeholder for interpolated values when generating the key for a translation.

Literal tags

§ k

Obtains the key for a certain literal:

import { k } from 'nano-i18n';

k`Hello, ${'World'}`;
// => "Hello, {}"

Keys are generated by replacing all values with the {} sequence.

Note: That means that currently, the strings you wish to translate may not contain the {} sequence.

You may change this by using the config method:

import { config } from 'nano-i18n';

config({
	placeholder: '@@'
});

§ v

Generates a translation function for a literal:

import { v } from 'nano-i18n';

v`Salut, ${0}!`;
// => function(strings, values) {}

When providing a translation, the interpolated values need to be numbers (i.e. ${0}, ${1}, et cetera). They don't necessarily need to be in sequential order, so you can swap them around if the translation needs it.

§ t

Get a translated string:

import { t } from 'nano-i18n';

t`Hello, ${'Dan'}!`;
// => "Salut, Dan!"

If there's no translation available, it returns the normal interpolated string instead, and logs a warning to the console.

You can also use t as a normal function for translating dynamic strings:

import { t } from 'nano-i18n';

t('Hello World');

This is useful for passing the t function to templating languages such as Mustache.

Further reading

• i18n with tagged template literals in ECMAScript 2015 by Jack Hsu
• Easy i18n in 10 lines of JavaScript (PoC) by Andrea Giammarchi
• i18n Tagged Template Literals by Steffen Kolmer