doc.md

Classes

MessageContext

Message contexts are single-language stores of translations. They are responsible for parsing translation resources in the FTL syntax and can format translation units (entities) to strings.

Always use MessageContext.format to retrieve translation units from a context. Translations can contain references to other entities or external arguments, conditional logic in form of select expressions, traits which describe their grammatical features, and can use FTL builtins which make use of the Intl formatters to format numbers, dates, lists and more into the context's language. See the documentation of the FTL syntax for more information.

MessageContext

RuntimeParser

The Parser class is responsible for parsing FTL resources.

It's only public method is getResource(source) which takes an FTL string and returns a two element Array with an Object of entries generated from the source as the first element and an array of SyntaxError objects as the second.

This parser is optimized for runtime performance.

There is an equivalent of this parser in syntax/parser which is generating full AST which is useful for FTL tools.

FTLType

The FTLType class is the base of FTL's type system.

FTL types wrap JavaScript values and store additional configuration for them, which can then be used in the toString method together with a proper Intl formatter.

FTLType

MessageContext

Message contexts are single-language stores of translations. They are responsible for parsing translation resources in the FTL syntax and can format translation units (entities) to strings.

Always use MessageContext.format to retrieve translation units from a context. Translations can contain references to other entities or external arguments, conditional logic in form of select expressions, traits which describe their grammatical features, and can use FTL builtins which make use of the Intl formatters to format numbers, dates, lists and more into the context's language. See the documentation of the FTL syntax for more information.

Kind: global class

• MessageContext
  • new MessageContext(lang, [options])
  • .addMessages(source) ⇒ Array.<Error>
  • .format(message, args, errors) ⇒ string

new MessageContext(lang, [options])

Create an instance of MessageContext.

The lang argument is used to instantiate Intl formatters used by translations. The options object can be used to configure the context.

Examples:

const ctx = new MessageContext(lang);

const ctx = new MessageContext(lang, { useIsolating: false });

const ctx = new MessageContext(lang, {
  useIsolating: true,
  functions: {
    NODE_ENV: () => process.env.NODE_ENV
  }
});

Available options:

• functions - an object of additional functions available to translations as builtins.

• useIsolating - boolean specifying whether to use Unicode isolation marks (FSI, PDI) for bidi interpolations.

Param	Type	Description
lang	string	Language of the context.
[options]	Object

messageContext.addMessages(source) ⇒ Array.<Error>

Add a translation resource to the context.

The translation resource must use the FTL syntax. It will be parsed by the context and each translation unit (message) will be available in the messages map by its identifier.

ctx.addMessages('foo = Foo');
ctx.messages.get('foo');

// Returns a raw representation of the 'foo' message.

Parsed entities should be formatted with the format method in case they contain logic (references, select expressions etc.).

Kind: instance method of MessageContext

Param	Type	Description
source	string	Text resource with translations.

messageContext.format(message, args, errors) ⇒ string

Format a message to a string or null.

Format a raw message from the context's messages map into a string (or a null if it has a null value). args will be used to resolve references to external arguments inside of the translation.

In case of errors format will try to salvage as much of the translation as possible and will still return a string. For performance reasons, the encountered errors are not returned but instead are appended to the errors array passed as the third argument.

const errors = [];
ctx.addMessages('hello = Hello, { $name }!');
const hello = ctx.messages.get('hello');
ctx.format(hello, { name: 'Jane' }, errors);

// Returns 'Hello, Jane!' and `errors` is empty.

ctx.format(hello, undefined, errors);

// Returns 'Hello, name!' and `errors` is now:

[<ReferenceError: Unknown external: name>]

Kind: instance method of MessageContext

Param	Type
message	Object | string
args	Object | undefined
errors	Array

MessageContext

Kind: global class

• MessageContext
  • new MessageContext(lang, [options])
  • .addMessages(source) ⇒ Array.<Error>
  • .format(message, args, errors) ⇒ string

new MessageContext(lang, [options])

Create an instance of MessageContext.

The lang argument is used to instantiate Intl formatters used by translations. The options object can be used to configure the context.

Examples:

const ctx = new MessageContext(lang);

const ctx = new MessageContext(lang, { useIsolating: false });

const ctx = new MessageContext(lang, {
  useIsolating: true,
  functions: {
    NODE_ENV: () => process.env.NODE_ENV
  }
});

Available options:

• functions - an object of additional functions available to translations as builtins.

• useIsolating - boolean specifying whether to use Unicode isolation marks (FSI, PDI) for bidi interpolations.

Param	Type	Description
lang	string	Language of the context.
[options]	Object

messageContext.addMessages(source) ⇒ Array.<Error>

Add a translation resource to the context.

The translation resource must use the FTL syntax. It will be parsed by the context and each translation unit (message) will be available in the messages map by its identifier.

ctx.addMessages('foo = Foo');
ctx.messages.get('foo');

// Returns a raw representation of the 'foo' message.

Parsed entities should be formatted with the format method in case they contain logic (references, select expressions etc.).

Kind: instance method of MessageContext

Param	Type	Description
source	string	Text resource with translations.

messageContext.format(message, args, errors) ⇒ string

Format a message to a string or null.

Format a raw message from the context's messages map into a string (or a null if it has a null value). args will be used to resolve references to external arguments inside of the translation.

In case of errors format will try to salvage as much of the translation as possible and will still return a string. For performance reasons, the encountered errors are not returned but instead are appended to the errors array passed as the third argument.

const errors = [];
ctx.addMessages('hello = Hello, { $name }!');
const hello = ctx.messages.get('hello');
ctx.format(hello, { name: 'Jane' }, errors);

// Returns 'Hello, Jane!' and `errors` is empty.

ctx.format(hello, undefined, errors);

// Returns 'Hello, name!' and `errors` is now:

[<ReferenceError: Unknown external: name>]

Kind: instance method of MessageContext

Param	Type
message	Object | string
args	Object | undefined
errors	Array

RuntimeParser

The Parser class is responsible for parsing FTL resources.

It's only public method is getResource(source) which takes an FTL string and returns a two element Array with an Object of entries generated from the source as the first element and an array of SyntaxError objects as the second.

This parser is optimized for runtime performance.

There is an equivalent of this parser in syntax/parser which is generating full AST which is useful for FTL tools.

Kind: global class

runtimeParser.getResource(string) ⇒ Array.<Object, Array>

Kind: instance method of RuntimeParser

Param	Type
string	string

FTLType

The FTLType class is the base of FTL's type system.

FTL types wrap JavaScript values and store additional configuration for them, which can then be used in the toString method together with a proper Intl formatter.

Kind: global class

• FTLType
  • new FTLType(value, opts)
  • .valueOf() ⇒ Any
  • .toString(ctx) ⇒ string

new FTLType(value, opts)

Create an FTLType instance.

Param	Type	Description
value	Any	JavaScript value to wrap.
opts	Object	Configuration.

ftlType.valueOf() ⇒ Any

Get the JavaScript value wrapped by this FTLType instance.

Kind: instance method of FTLType

ftlType.toString(ctx) ⇒ string

Stringify an instance of FTLType.

This method can use Intl formatters memoized by the MessageContext instance passed as an argument.

Kind: instance method of FTLType

Param	Type
ctx	MessageContext

FTLType

Kind: global class

• FTLType
  • new FTLType(value, opts)
  • .valueOf() ⇒ Any
  • .toString(ctx) ⇒ string

new FTLType(value, opts)

Create an FTLType instance.

Param	Type	Description
value	Any	JavaScript value to wrap.
opts	Object	Configuration.

ftlType.valueOf() ⇒ Any

Get the JavaScript value wrapped by this FTLType instance.

Kind: instance method of FTLType

ftlType.toString(ctx) ⇒ string

Stringify an instance of FTLType.

This method can use Intl formatters memoized by the MessageContext instance passed as an argument.

Kind: instance method of FTLType

Param	Type
ctx	MessageContext

dox.md

Global

---

exports(ctx, args, message, errors)

Format a translation into an FTLType.

The return value must be sringified with its toString method by the caller.

Parameters

ctx: MessageContext, Format a translation into an FTLType.

The return value must be sringified with its toString method by the caller.

args: Object, Format a translation into an FTLType.

The return value must be sringified with its toString method by the caller.

message: Object, Format a translation into an FTLType.

The return value must be sringified with its toString method by the caller.

errors: Array, Format a translation into an FTLType.

The return value must be sringified with its toString method by the caller.

Returns: FTLType

---

Overview: The role of the FTL resolver is to format a translation object to an instance of FTLType.

Translations can contain references to other messages or external arguments, conditional logic in form of select expressions, traits which describe their grammatical features, and can use FTL builtins which make use of the Intl formatters to format numbers, dates, lists and more into the context's language. See the documentation of the FTL syntax for more information.

In case of errors the resolver will try to salvage as much of the translation as possible. In rare situations where the resolver didn't know how to recover from an error it will return an instance of FTLNone.

MessageReference, VariantExpression, AttributeExpression and SelectExpression resolve to raw Runtime Entries objects and the result of the resolution needs to be passed into Value to get their real value. This is useful for composing expressions. Consider:

brand-name[nominative]

which is a VariantExpression with properties id: MessageReference and key: Keyword. If MessageReference was resolved eagerly, it would instantly resolve to the value of the brand-name message. Instead, we want to get the message object and look for its nominative variant.

All other expressions (except for FunctionReference which is only used in CallExpression) resolve to an instance of FTLType, which must then be sringified with its toString method by the caller.