Tannin

Tannin is a gettext localization library.

Inspired by Jed, it is built to be largely compatible with Jed-formatted locale data, and even offers a Jed drop-in replacement compatibility shim to easily convert an existing project. Contrasted with Jed, it is more heavily optimized for performance and bundle size. While Jed works well with one-off translations, it suffers in single-page applications with repeated rendering of elements. Using Tannin, you can expect a bundle size 20% that of Jed (984 bytes gzipped) and upwards of 330x better performance (see benchmarks). It does so without sacrificing the safety of plural forms evaluation, using a hand-crafted expression parser in place of the verbose compiled grammar included in Jed.

Furthermore, the project is architected as a mono-repo, published on npm under the @tannin scope. These modules can be used standalone, with or without Tannin. For example, you may find value in @tannin/compile for creating an expression evaluator, or @tannin/sprintf as a minimal printf string formatter.

The following modules are available:

• tannin
• @tannin/compat
• @tannin/compile
• @tannin/evaluate
• @tannin/plural-forms
• @tannin/postfix
• @tannin/sprintf

Installation

Using npm as a package manager:

npm install tannin

Otherwise, download a pre-built copy from unpkg:

https://unpkg.com/tannin/dist/tannin.min.js

Usage

Construct a new instance of Tannin, passing locale data in the form of a Jed-formatted JSON object.

The returned Tannin instance includes the fully-qualified dcnpgettext function to retrieve a translated string.

1import Tannin from 'tannin';
2
3const i18n = new Tannin({
4	the_domain: {
5		'': {
6			domain: 'the_domain',
7			lang: 'en',
8			plural_forms: 'nplurals=2; plural=(n != 1);',
9		},
10		example: ['singular translation', 'plural translation'],
11	},
12});
13
14i18n.dcnpgettext('the_domain', undefined, 'example');
15// ⇒ 'singular translation'

Tannin accepts plural_forms both as a standard gettext plural forms string or as a function which, given a number, should return the (zero-based) plural form index. Providing plural_forms as a function can yield a performance gain of approximately 8x for plural evaluation.

For example, consider the following "default" English (untranslated) initialization:

1const i18n = new Tannin({
2	messages: {
3		'': {
4			domain: 'messages',
5			plural_forms: (n) => (n === 1 ? 0 : 1),
6		},
7	},
8});
9
10i18n.dcnpgettext('messages', undefined, 'example', 'examples', 1);
11// ⇒ 'example'
12
13i18n.dcnpgettext('messages', undefined, 'example', 'examples', 2);
14// ⇒ 'examples'

Jed Compatibility

For a more human-friendly API, or to more easily transition an existing project, consider using @tannin/compat as a drop-in replacement for Jed.

1import Jed from '@tannin/compat';
2
3const i18n = new Jed({
4	locale_data: {
5		the_domain: {
6			'': {
7				domain: 'the_domain',
8				lang: 'en',
9				plural_forms: 'nplurals=2; plural=(n != 1);',
10			},
11			example: ['singular translation', 'plural translation'],
12		},
13	},
14	domain: 'the_domain',
15});
16
17i18n.translate('example').fetch();
18// ⇒ 'singular translation'

Benchmarks

The following benchmarks are performed in Node 10.16.0 on a MacBook Pro (2019), 2.4 GHz 8-Core Intel Core i9, 32 GB 2400 MHz DDR4 RAM.

Singular
---
Tannin x 216,670,213 ops/sec ±0.73% (90 runs sampled)
Tannin (Optimized Default) x 219,477,869 ops/sec ±0.32% (96 runs sampled)
Jed x 58,730,499 ops/sec ±0.34% (96 runs sampled)


Singular (Untranslated)
---
Tannin x 75,835,743 ops/sec ±1.26% (96 runs sampled)
Tannin (Optimized Default) x 76,474,169 ops/sec ±0.61% (92 runs sampled)
Jed x 241,632 ops/sec ±0.73% (96 runs sampled)


Plural
---
Tannin x 7,108,006 ops/sec ±0.96% (95 runs sampled)
Tannin (Optimized Default) x 51,658,190 ops/sec ±1.25% (94 runs sampled)
Jed x 236,797 ops/sec ±0.98% (97 runs sampled)

To run benchmarks on your own machine:

git clone https://github.com/aduth/tannin.git
cd tannin
npm install
node packages/tannin/benchmark

License

Copyright 2019-2024 Andrew Duthie

Released under the MIT License.