@drewjbartlett/i17n

i17n

A lightweight (1.4kB) internationalization library tailored for startups and small-to-medium sized projects, offering a simple and efficient solution for managing translations in a single language without the overhead of a bloated library.

Features

• ✅ basic { "key": "value" } translations t('key')
• ✅ nested { "key": "child": "value" } translations t('key.child')
• ✅ interpolated values t('Hello, {name}!', { name: 'Drew' })
• ✅ count based translations t('tree', { count: 1 }) // "tree", t('tree', { count: 10 }) // "trees"
• ✅ smart caching - after a key is resolved once it is read from a cache
• ✅ extending core translations
• ✅ lightweight - 1.4kB
• ✅ TypeScript Support

Why i17n?

i17n is intended to inform that this is not a full-fledged i18n library. There is only support for a single set of translations or language at a time. If your project is smaller or a startup with no need for multiple languages yet, but may need them in the future, the i18n familiar API of i17n is exactly what you need.

Using internationalization is not just for languages. It helps create a consistent UX for your application and separates the concerns of text and UIs. Imagine your application sometimes says "Add Item" and other times says "Create Item" and even worse, says "New Item" in other places. This can be confusing to some users and leads to an inconsistent user experience. i17n allows you to have a single definition { "addItem": "Add {item}" } that you can reference all over your application, t('addItem', { item: 'model.name' }).

Installation

npm i @drewjbartlett/i17n --save

Usage

{
  "helloWorld": "Hello World!",
  "welcomeUser": "Welcome, {user}!",
  "global": {
    "edit": "Edit",
    "save": "Save",
    "addNew": "Add New {item}",
  },
  "item": {
    "name__one": "Item",
    "name__many": "Items",
  },
}

// or translations.ts
export const lang = {
  helloWorld: 'Hello World!,
  welcomeUser: 'Welcome, {user}!',
  user: {
    name: 'User',
  },
  global: {
    edit: 'Edit',
    save: 'Save',
    addNew: 'Add New {item}',
  },
  item: {
    name__one: 'Item',
    name__many: 'Items',
  },
};

// i17n.ts
import { createI7n } from '@drewjbartlett/i17n'
import Translations from 'path/to/translations';

export const i17n = createI17n({
  translations: Translations,
});

// another-file.ts
import { i17n } from 'path/to/i17n'

i17n.t('helloWorld'); // "Hello World"

Optionally you can export your i17n's API to fit your convention and needs.

const $t = i18n.t;

export { $t }

// another-file.ts
import { $t } from 'path/to/i17n'

$t('helloWorld')

Config

Value	Description
translations	The core { key: value } translations.
loggingEnabled	When enabled warning logs will write to the console for missing keys.
cache	Optionally pass a prebuilt cache of the resolved { key: value } pairs.

API

• t - Attempt to resolve a translation

{
  "topLevel": "Top Level",
  "namespace": {
    "anotherNamespace": {
      "tooDeep": "Deeply Namespaced Value"
    }
  },
  "withAnInterpolation": "Hey, {name}!",
  "withCounts": {
    "mouse__one": "Mouse",
    "mouse__many": "Mice",
  }
}

When calling t(), the each level of the keys are denoted by a .. For example:

i18n.t('topLevel') // "Top Level"
i18n.t('namespace.anotherNamespace.tooDeep') // "Deeply Namespaced Value"

Tip: Don't nest too deeply or the first time a key is resolved it will have to iterate n times to resolve it. After the first time it's cached.

Interpolations

When interpolating values, you simply pass put a value in your translation wrapped in {}.

i18n.t('withAnInterpolation', { name: 'Drew' }) // "Hey, Drew!"
i18n.t('withAnInterpolation', { name: 'Robin' }) // "Hey, Robin!"

Count Based

Keeping with the example above, there are times when a translation should resolve based on a given count. To do this simply provide a key of the same name and postfix it with __one or __many.

i18n.t('withCounts.mouse', { count: 1 }) // "Mouse"
i18n.t('withCounts.mouse', { count: 10 }) // "Mice"

Extending

There may be times where a core i17n instance is shipped. Imagine your global translations are included.

export const i17n = createI17n({
  translations: {
    global: {
      edit: "Edit",
      save: "Save",
      addNew: "Add New {item}",
    },
  },
});

However, other parts of your application may want to extend and include their own translations that don't ship as core translations. This is especially useful when lazy loading translations in Single Page Apps.

// my-app-1.ts
import { i17n } from 'path/to/i17n'

i17n.extend({
  myApp1: {
    someKey: '...',
    anotherKey: '...',
  }
});

// now both the original and extended translations may be used
i17n.t('myApp1.someKey')
i17n.t('global.edit')

Usage with Vue

i17n can be used in any application but to show how easy it is to use with a library like Vue, here are some examples.

Vue 3

// i17n.ts
import { createI7n } from '@drewjbartlett/i17n'
import Translations from 'path/to/translations';

const i17n = createI17n({
  translations: Translations,
});

const I18nPlugin = {
  install(app) {
    app.config.globalProperties.$t = i18n.t;
  },
};

const app = createApp(MainApp);

app.use(I18nPlugin);

<template>
  <h1>{{ $t('welcomeUser', { user: myUser }) }}</h1>
</template>

Vue 2

import Vue from 'vue';

const I18nPlugin = {
  install: (Vue) => {
    Vue.prototype.$t = i18n.t;
  },
};

Vue.use(I18nPlugin)

<template>
  <h1>{{ $t('welcomeUser', { user: myUser }) }}</h1>
</template>