I18n | i18n-js v4.0.0-alpha.14

Hierarchy

I18n

Index

Constructors

constructor

Properties

Accessors

Methods

Constructors

constructor

new I18n(translations?: Dict, options?: Partial<I18nOptions>): I18n

- Defined in I18n.ts:192
Parameters
- translations: Dict = {}
- options: Partial<I18nOptions> = {}
Returns I18n

Properties

defaultSeparator

defaultSeparator: string

Set the default string separator. Defaults to ., as in scope.translation.

distanceOfTimeInWords

distanceOfTimeInWords: (fromTime: DateTime, toTime: DateTime, options?: TimeAgoInWordsOptions) => string = ...

alias: timeAgoInWords

Type declaration

- (fromTime: DateTime, toTime: DateTime, options?: TimeAgoInWordsOptions): string
- Reports the approximate distance in time between two time representations.
  
  Parameters
  - fromTime: DateTime
    
    The initial time.
  - toTime: DateTime
    
    The ending time. Defaults to Date.now().
  - options: TimeAgoInWordsOptions = {}
    
    The options.
  Returns string
  
  The distance in time representation.

enableFallback

enableFallback: boolean

Set if engine should fallback to the default locale when a translation is missing. Defaults to false.

When enabled, missing translations will first be looked for in less specific versions of the requested locale and if that fails by taking them from your I18n#defaultLocale.

l

l: (type: string, value: undefined | null | string | number | Date, options?: Dict) => string = ...

alias: localize

Type declaration

- (type: string, value: undefined | null | string | number | Date, options?: Dict): string
- Localize several values.
  
  You can provide the following scopes: currency, number, or percentage. If you provide a scope that matches the /^(date|time)/ regular expression then the value will be converted by using the I18n.toTime function. It will default to the value's toString function.
  
  If value is either null or undefined then an empty string will be returned, regardless of that localization type has been used.
  
  Parameters
  - type: string
    
    The localization type.
  - value: undefined | null | string | number | Date
    
    The value that must be localized.
  - Optional options: Dict
    
    The localization options.
  Returns string
  
  The localized string.

locales

locales: Locales

The locale resolver registry.

see: Locales

missingBehavior

missingBehavior: string

Set missing translation behavior.

message will display a message that the translation is missing.
guess will try to guess the string.
error will raise an exception whenever a translation is not defined.

See MissingTranslation.register for instructions on how to define your own behavior.

missingPlaceholder

missingPlaceholder: MissingPlaceholderHandler

Return a missing placeholder message for given parameters.

missingTranslation

missingTranslation: MissingTranslation

The missing translation behavior registry.

see: MissingTranslation

missingTranslationPrefix

missingTranslationPrefix: string

If you use missingBehavior with 'message', but want to know that the string is actually missing for testing purposes, you can prefix the guessed string by setting the value here. By default, no prefix is used.

nullPlaceholder

nullPlaceholder: NullPlaceholderHandler

Return a placeholder message for null values. Defaults to the same behavior as I18n.missingPlaceholder.

onChangeHandlers

onChangeHandlers: OnChangeHandler[] = []

List of all onChange handlers.

p

p: (count: number, scope: Scope, options?: TranslateOptions) => string = ...

alias: pluralize

Type declaration

- (count: number, scope: Scope, options?: TranslateOptions): string
- Pluralize the given scope using the count value. The pluralized translation may have other placeholders, which will be retrieved from options.
  
  Parameters
  - count: number
    
    The counting number.
  - scope: Scope
    
    The translation scope.
  - Optional options: TranslateOptions
    
    The translation options.
  Returns string
  
  The translated string.

placeholder

placeholder: RegExp

Set the placeholder format. Accepts {{placeholder}} and %{placeholder}.

pluralization

pluralization: Pluralization

The pluralization behavior registry.

see: Pluralization

t

t: (scope: Scope, options?: TranslateOptions) => string = ...

alias: translate

Type declaration

- (scope: Scope, options?: TranslateOptions): string
- Translate the given scope with the provided options.
  
  Parameters
  - scope: Scope
    
    The scope that will be used.
  - Optional options: TranslateOptions
    
    The options that will be used on the translation. Can include some special options like defaultValue, count, and scope. Everything else will be treated as replacement values.
  Returns string
  
  The translated string.

transformKey

transformKey: (key: string) => string

Transform keys. By default, it returns the key as it is, but allows for overriding. For instance, you can set a function to receive the camelcase key, and convert it to snake case.

Type declaration

- (key: string): string
- Parameters
  - key: string
  Returns string

translations

translations: Dict = {}

Set the registered translations. The root key must always be the locale (and its variations with region).

Remember that no events will be triggered if you change this object directly. To trigger onchange events, you must perform updates either using I18n#store or I18n#update.

Accessors

defaultLocale

get defaultLocale(): string
set defaultLocale(newLocale: string): void

- Defined in I18n.ts:287
Return the default locale, using a explicit locale set using i18n.defaultLocale = locale, the default locale set using i18n.defaultLocale or the fallback, which is en.

Returns string

The current locale.
- Defined in I18n.ts:296
Set the default locale explicitly.

Parameters
- newLocale: string
  
  The new locale.
Returns void

The current locale.

locale

get locale(): string
set locale(newLocale: string): void

- Defined in I18n.ts:255
Return the current locale, using a explicit locale set using i18n.locale = newLocale, the default locale set using i18n.defaultLocale or the fallback, which is en.

Returns string

The current locale.
- Defined in I18n.ts:264
Set the current locale explicitly.

Parameters
- newLocale: string
  
  The new locale.
Returns void

The current locale.

version

get version(): number

- Defined in I18n.ts:1364
Return the change version. This value is incremented whenever I18n#store or I18n#update is called, or when I18n#locale/I18n#defaultLocale is set.

Returns number

Methods

localize

localize(type: string, value: undefined | null | string | number | Date, options?: Dict): string

- Defined in I18n.ts:432
Localize several values.

You can provide the following scopes: currency, number, or percentage. If you provide a scope that matches the /^(date|time)/ regular expression then the value will be converted by using the I18n.toTime function. It will default to the value's toString function.

If value is either null or undefined then an empty string will be returned, regardless of that localization type has been used.

Parameters
- type: string
  
  The localization type.
- value: undefined | null | string | number | Date
  
  The value that must be localized.
- Optional options: Dict
  
  The localization options.
Returns string

The localized string.

numberToCurrency

numberToCurrency(input: Numeric, options?: Partial<FormatNumberOptions>): string

Formats a number into a currency string (e.g., $13.65). You can customize the format in the using an options object.

The currency unit and number formatting of the current locale will be used unless otherwise specified in the provided options. No currency conversion is performed. If the user is given a way to change their locale, they will also be able to change the relative value of the currency displayed with this helper.

example

i18n.numberToCurrency(1234567890.5);
// => "$1,234,567,890.50"

i18n.numberToCurrency(1234567890.506);
// => "$1,234,567,890.51"

i18n.numberToCurrency(1234567890.506, { precision: 3 });
// => "$1,234,567,890.506"

i18n.numberToCurrency("123a456");
// => "$123a456"

i18n.numberToCurrency("123a456", { raise: true });
// => raises exception ("123a456" is not a valid numeric value)

i18n.numberToCurrency(-0.456789, { precision: 0 });
// => "$0"

i18n.numberToCurrency(-1234567890.5, { negativeFormat: "(%u%n)" });
// => "($1,234,567,890.50)"

i18n.numberToCurrency(1234567890.5, {
  unit: "&pound;",
  separator: ",",
  delimiter: "",
});
// => "&pound;1234567890,50"

i18n.numberToCurrency(1234567890.5, {
  unit: "&pound;",
  separator: ",",
  delimiter: "",
  format: "%n %u",
});
// => "1234567890,50 &pound;"

i18n.numberToCurrency(1234567890.5, { stripInsignificantZeros: true });
// => "$1,234,567,890.5"

i18n.numberToCurrency(1234567890.5, { precision: 0, roundMode: "up" });
// => "$1,234,567,891"

Parameters

input: Numeric

The number to be formatted.
options: Partial<FormatNumberOptions> = {}

The formatting options. When defined, supersedes the default options defined by number.format and number.currency.*.

Returns string

The formatted number.

numberToDelimited

numberToDelimited(input: Numeric, options?: Partial<NumberToDelimitedOptions>): string

Formats a +number+ with grouped thousands using delimiter (e.g., 12,324). You can customize the format in the options parameter.

example

i18n.numberToDelimited(12345678);
// => "12,345,678"

i18n.numberToDelimited("123456");
// => "123,456"

i18n.numberToDelimited(12345678.05);
// => "12,345,678.05"

i18n.numberToDelimited(12345678, { delimiter: "." });
// => "12.345.678"

i18n.numberToDelimited(12345678, { delimiter: "," });
// => "12,345,678"

i18n.numberToDelimited(12345678.05, { separator: " " });
// => "12,345,678 05"

i18n.numberToDelimited("112a");
// => "112a"

i18n.numberToDelimited(98765432.98, { delimiter: " ", separator: "," });
// => "98 765 432,98"

i18n.numberToDelimited("123456.78", {
  delimiterPattern: /(\d+?)(?=(\d\d)+(\d)(?!\d))/g,
});
// => "1,23,456.78"

Parameters

input: Numeric

The numeric value that will be formatted.
options: Partial<NumberToDelimitedOptions> = {}

The formatting options.

Returns string

The formatted number.

numberToHuman

numberToHuman(input: Numeric, options?: Partial<NumberToHumanOptions>): string

Convert a number into a readable representation.

example

i18n.numberToHuman(123);
// => "123"

i18n.numberToHuman(1234);
// => "1.23 Thousand"

i18n.numberToHuman(12345);
// => "12.3 Thousand"

i18n.numberToHuman(1234567);
// => "1.23 Million"

i18n.numberToHuman(1234567890);
// => "1.23 Billion"

i18n.numberToHuman(1234567890123);
// => "1.23 Trillion"

i18n.numberToHuman(1234567890123456);
// => "1.23 Quadrillion"

i18n.numberToHuman(1234567890123456789);
// => "1230 Quadrillion"

i18n.numberToHuman(489939, { precision: 2 });
// => "490 Thousand"

i18n.numberToHuman(489939, { precision: 4 });
// => "489.9 Thousand"

i18n.numberToHuman(489939, { precision: 2, roundMode: "down" });
// => "480 Thousand"

i18n.numberToHuman(1234567, { precision: 4, significant: false });
// => "1.2346 Million"

i18n.numberToHuman(1234567, {
  precision: 1,
  separator: ",",
  significant: false,
});
// => "1,2 Million"

i18n.numberToHuman(500000000, { precision: 5 });
// => "500 Million"

i18n.numberToHuman(12345012345, { significant: false });
// => "12.345 Billion"

Non-significant zeros after the decimal separator are stripped out by default (set stripInsignificantZeros to false to change that):

i18n.numberToHuman(12.00001);
// => "12"

i18n.numberToHuman(12.00001, { stripInsignificantZeros: false });
// => "12.0"

You can also use your own custom unit quantifiers:

i18n.numberToHuman(500000, units: { unit: "ml", thousand: "lt" });
// => "500 lt"

If in your I18n locale you have:

---
en:
  distance:
    centi:
      one: "centimeter"
      other: "centimeters"
    unit:
      one: "meter"
      other: "meters"
    thousand:
      one: "kilometer"
      other: "kilometers"
    billion: "gazillion-distance"

Then you could do:

i18n.numberToHuman(543934, { units: "distance" });
// => "544 kilometers"

i18n.numberToHuman(54393498, { units: "distance" });
// => "54400 kilometers"

i18n.numberToHuman(54393498000, { units: "distance" });
// => "54.4 gazillion-distance"

i18n.numberToHuman(343, { units: "distance", precision: 1 });
// => "300 meters"

i18n.numberToHuman(1, { units: "distance" });
// => "1 meter"

i18n.numberToHuman(0.34, { units: "distance" });
// => "34 centimeters"

Parameters

input: Numeric

The number that will be formatted.
options: Partial<NumberToHumanOptions> = {}

The formatting options. When defined, supersedes the default options stored at number.human.format.* and number.human.storage_units.*.

Returns string

The formatted number.

numberToHumanSize

numberToHumanSize(input: Numeric, options?: Partial<NumberToHumanSizeOptions>): string

Convert a number into a readable size representation.

example

i18n.numberToHumanSize(123)
// => "123 Bytes"

i18n.numberToHumanSize(1234)
// => "1.21 KB"

i18n.numberToHumanSize(12345)
// => "12.1 KB"

i18n.numberToHumanSize(1234567)
// => "1.18 MB"

i18n.numberToHumanSize(1234567890)
// => "1.15 GB"

i18n.numberToHumanSize(1234567890123)
// => "1.12 TB"

i18n.numberToHumanSize(1234567890123456)
// => "1.1 PB"

i18n.numberToHumanSize(1234567890123456789)
// => "1.07 EB"

i18n.numberToHumanSize(1234567, {precision: 2})
// => "1.2 MB"

i18n.numberToHumanSize(483989, precision: 2)
// => "470 KB"

i18n.numberToHumanSize(483989, {precision: 2, roundMode: "up"})
// => "480 KB"

i18n.numberToHumanSize(1234567, {precision: 2, separator: ","})
// => "1,2 MB"

i18n.numberToHumanSize(1234567890123, {precision: 5})
// => "1.1228 TB"

i18n.numberToHumanSize(524288000, {precision: 5})
// => "500 MB"

Parameters

input: Numeric

The number that will be formatted.
options: Partial<NumberToHumanSizeOptions> = {}

The formatting options. When defined, supersedes the default options stored at number.human.storage_units.* and number.human.format.

Returns string

The formatted number.

numberToPercentage

numberToPercentage(input: Numeric, options?: Partial<NumberToPercentageOptions>): string

Convert a number into a formatted percentage value.

example

i18n.numberToPercentage(100);
// => "100.000%"

i18n.numberToPercentage("98");
// => "98.000%"

i18n.numberToPercentage(100, { precision: 0 });
// => "100%"

i18n.numberToPercentage(1000, { delimiter: ".", separator: "," });
// => "1.000,000%"

i18n.numberToPercentage(302.24398923423, { precision: 5 });
// => "302.24399%"

i18n.numberToPercentage(1000, { precision: null });
// => "1000%"

i18n.numberToPercentage("98a");
// => "98a%"

i18n.numberToPercentage(100, { format: "%n  %" });
// => "100.000  %"

i18n.numberToPercentage(302.24398923423, { precision: 5, roundMode: "down" });
// => "302.24398%"

Parameters

input: Numeric

The number to be formatted.
options: Partial<NumberToPercentageOptions> = {}

The formatting options. When defined, supersedes the default options stored at number.format and number.percentage.*.

Returns string

The formatted number.

numberToRounded

numberToRounded(input: Numeric, options?: Partial<NumberToRoundedOptions>): string

Convert number to a formatted rounded value.

example

i18n.numberToRounded(111.2345);
// => "111.235"

i18n.numberToRounded(111.2345, { precision: 2 });
// => "111.23"

i18n.numberToRounded(13, { precision: 5 });
// => "13.00000"

i18n.numberToRounded(389.32314, { precision: 0 });
// => "389"

i18n.numberToRounded(111.2345, { significant: true });
// => "111"

i18n.numberToRounded(111.2345, { precision: 1, significant: true });
// => "100"

i18n.numberToRounded(13, { precision: 5, significant: true });
// => "13.000"

i18n.numberToRounded(13, { precision: null });
// => "13"

i18n.numberToRounded(389.32314, { precision: 0, roundMode: "up" });
// => "390"

i18n.numberToRounded(13, {
  precision: 5,
  significant: true,
  stripInsignificantZeros: true,
});
// => "13"

i18n.numberToRounded(389.32314, { precision: 4, significant: true });
// => "389.3"

i18n.numberToRounded(1111.2345, {
  precision: 2,
  separator: ",",
  delimiter: ".",
});
// => "1.111,23"

Parameters

input: Numeric

The number to be formatted.
Optional options: Partial<NumberToRoundedOptions>

The formatting options.

Returns string

The formatted number.

onChange

onChange(callback: OnChangeHandler): void

- Defined in I18n.ts:1355
Add a callback that will be executed whenever locale/defaultLocale changes, or I18n#store / I18n#update is called.

Parameters
- callback: OnChangeHandler
  
  The callback that will be executed.
Returns void

pluralize

pluralize(count: number, scope: Scope, options?: TranslateOptions): string

- Defined in I18n.ts:400
Pluralize the given scope using the count value. The pluralized translation may have other placeholders, which will be retrieved from options.

Parameters
- count: number
  
  The counting number.
- scope: Scope
  
  The translation scope.
- Optional options: TranslateOptions
  
  The translation options.
Returns string

The translated string.

store

store(translations: Dict): void

- Defined in I18n.ts:238
Update translations by merging them. Newest translations will override existing ones.

Parameters
- translations: Dict
  
  An object containing the translations that will be merged into existing translations.
Returns void

strftime

strftime(date: Date, format: string, options?: Partial<StrftimeOptions>): string

- Defined in I18n.ts:1181
Formats time according to the directives in the given format string. The directives begins with a percent (%) character. Any text not listed as a directive will be passed through to the output string.

see

strftime

Parameters
- date: Date
  
  The date that will be formatted.
- format: string
  
  The formatting string.
- options: Partial<StrftimeOptions> = {}
  
  The formatting options.
Returns string

The formatted date.

timeAgoInWords

timeAgoInWords(fromTime: DateTime, toTime: DateTime, options?: TimeAgoInWordsOptions): string

- Defined in I18n.ts:1334
Reports the approximate distance in time between two time representations.

Parameters
- fromTime: DateTime
  
  The initial time.
- toTime: DateTime
  
  The ending time. Defaults to Date.now().
- options: TimeAgoInWordsOptions = {}
  
  The options.
Returns string

The distance in time representation.

toSentence

toSentence(items: any[], options?: Partial<ToSentenceOptions>): string

- Defined in I18n.ts:1282
Converts the array to a comma-separated sentence where the last element is joined by the connector word.
example
```
i18n.toSentence(["apple", "banana", "pineapple"]);
//=> apple, banana, and pineapple.
```
Parameters
- items: any[]
  
  The list of items that will be joined.
- options: Partial<ToSentenceOptions> = {}
  
  The options.
Returns string

The joined string.

toTime

toTime(scope: Scope, input: DateTime): string

- Defined in I18n.ts:488
Convert the given dateString into a formatted date.

Parameters
- scope: Scope
  
  The formatting scope.
- input: DateTime
  
  The string that must be parsed into a Date object.
Returns string

The formatted date.

translate

translate(scope: Scope, options?: TranslateOptions): string

- Defined in I18n.ts:336
Translate the given scope with the provided options.

Parameters
- scope: Scope
  
  The scope that will be used.
- Optional options: TranslateOptions
  
  The options that will be used on the translation. Can include some special options like defaultValue, count, and scope. Everything else will be treated as replacement values.
Returns string

The translated string.

update

update(path: string, override: any, options?: { strict: boolean }): void

- Defined in I18n.ts:1225
You may want to update a part of your translations. This is a public interface for doing it so.

If the provided path exists, it'll be replaced. Otherwise, a new node will be created. When running in strict mode, paths that doesn't already exist will raise an exception.

Strict mode will also raise an exception if the override type differs from previous node type.
example
```
i18n.update("en.number.format", {unit: "%n %u"});
i18n.update("en.number.format", {unit: "%n %u"}, true);
```
Parameters
- path: string
  
  The path that's going to be updated. It must include the language, as in en.messages.
- override: any
  
  The new translation node.
- options: { strict: boolean } = ...
  
  Set options.
  - strict: boolean
    
    Raise an exception if path doesn't already exist, or if previous node's type differs from new node's type.
Returns void

withLocale

withLocale(locale: string, callback: () => void): Promise<void>

- Defined in I18n.ts:1155
Executes function with given locale set. The locale will be changed only during the callback's execution, switching back to the previous value once it finishes (with or without errors).

This is an asynchronous call, which means you must use await or you may end up with a race condition.
example
```
await i18n.withLocale("pt", () => {
  console.log(i18n.t("hello"));
});
```
Parameters
- locale: string
  
  The temporary locale that will be set during the function's execution.
- callback: () => void
  
  The function that will be executed with a temporary locale set.
  - - (): void
    - Returns void
Returns Promise<void>

Hierarchy

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Parameters

translations: Dict = {}

options: Partial<I18nOptions> = {}

Returns I18n

Properties

defaultSeparator

distanceOfTimeInWords

Type declaration

Parameters

fromTime: DateTime

toTime: DateTime

options: TimeAgoInWordsOptions = {}

Returns string

enableFallback

l

Type declaration

Parameters

type: string

value: undefined | null | string | number | Date

Optional options: Dict

Returns string

locales

missingBehavior

missingPlaceholder

missingTranslation

missingTranslationPrefix

nullPlaceholder

onChangeHandlers

p

Type declaration

Parameters

count: number

scope: Scope

Optional options: TranslateOptions

Returns string

placeholder

pluralization

t

Type declaration

Parameters

scope: Scope

Optional options: TranslateOptions

Returns string

transformKey

Type declaration

Parameters

key: string

Returns string

translations

Accessors

defaultLocale

Returns string

Parameters

newLocale: string

Returns void

locale

Returns string

Parameters

newLocale: string

Returns void

version

Returns number

Methods

localize

Parameters

type: string

value: undefined | null | string | number | Date

Optional options: Dict

Returns string

numberToCurrency

Parameters

input: Numeric