translator-pluralizer v1.0.0

translator-pluralizer

Add pluralization support to translator-factory functions.

This module uses the ECMAScript Internationalization API to narrow a message selection based on plurality rules.

Specifically, to see what keys you should use in your translation messages:

// The `type` option defaults to "cardinal", but could be "ordinal".
const rules = new Intl.PluralRules("en-US", { type: "cardinal" });

console.log(rules.select(1)); // outputs: "one"
console.log(rules.select(2)); // outputs: "other"

Getting started

Install

$ npm install translator-factory translator-pluralizer

Example

const createTranslatorFactory = require("translator-factory");
const createTranslatorPluralizer = require("translator-pluralizer");

const data = {
	en: {
		apples: {
			one: "an apple",
			other: "a bunch of apples",
		},
	},
};

const selectorPlugins = [createTranslatorPluralizer];

const getTranslator = createTranslatorFactory(data, { selectorPlugins });

const translate = getTranslator("en-US");

console.log(translate({ key: "apples", count: 1 })); // outputs: "an apple"

API

For all of the following examples, options is assumed to be:

const options = {
	selectorPlugins: [createTranslatorPluralizer],
	templateCompiler: (string) => handlebars.compile(string),
};

The selectorPlugins option tells the translator-factory instance to look for extra options in the message selector and use those to narrow the selection based on the plurality rules described in the introduction.

Specifically, the message selector may contain count for the cardinal rules or rank for the ordinal rules. Both are expected to be a number. The values provided for both are included in the values message selector property to be available for template placeholder substitution, and can be overridden for this purpose by providing either count or rank in values.

The templateCompiler option tells translator-factory to pass the message strings through the provided template engine (in this case, handlebars) during compilation. A template engine is not required to use this plugin, but it's helpful.

Selecting a message based on a cardinal number

const data = {
	en: {
		duration: {
			one: "{{count}} second",
			other: "{{multiple}} seconds",
		},
	},
};

const getTranslator = createTranslatorFactory(data, options);

const translate = getTranslator("en-US");

const key = "duration";

console.log(translate({ key, count: 1 })); // outputs: "1 second"
console.log(translate({ key, count: 5 })); // outputs: "5 seconds"
console.log(translate({ key, count: 0, values: { count: "no" } })); // outputs: "no seconds"

Selecting a message based on an ordinal number

const data = {
	en: {
		order: {
			one: "{{rank}}st",
			two: "{{rank}}nd",
			few: "{{rank}}rd",
			other: "{{rank}}th",
		},
	},
};

const getTranslator = createTranslatorFactory(data, options);

const translate = getTranslator("en-US");

const key = "duration";

console.log(translate({ key, rank: 1 })); // outputs: "1st"
console.log(translate({ key, rank: 5 })); // outputs: "5th"

Contributing

Testing

$ npm test