gecko-dev/intl/l10n/Fluent.jsm

1225 строки
35 KiB
JavaScript
Исходник Ответственный История

/* vim: set ts=2 et sw=2 tw=80 filetype=javascript: */
/* Copyright 2019 Mozilla Foundation and others
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/* fluent@0.12.0 */
/* global Intl */
/**
* The `FluentType` class is the base of Fluent's type system.
*
* Fluent 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.
*/
class FluentType {
/**
* Create an `FluentType` instance.
*
* @param {Any} value - JavaScript value to wrap.
* @param {Object} opts - Configuration.
* @returns {FluentType}
*/
constructor(value, opts) {
this.value = value;
this.opts = opts;
}
/**
* Unwrap the raw value stored by this `FluentType`.
*
* @returns {Any}
*/
valueOf() {
return this.value;
}
/**
* Format this instance of `FluentType` to a string.
*
* Formatted values are suitable for use outside of the `FluentBundle`.
* This method can use `Intl` formatters memoized by the `FluentBundle`
* instance passed as an argument.
*
* @param {FluentBundle} [bundle]
* @returns {string}
*/
toString() {
throw new Error("Subclasses of FluentType must implement toString.");
}
}
class FluentNone extends FluentType {
toString() {
return this.value || "???";
}
}
class FluentNumber extends FluentType {
constructor(value, opts) {
super(parseFloat(value), opts);
}
toString(bundle) {
try {
const nf = bundle._memoizeIntlObject(
Intl.NumberFormat, this.opts
);
return nf.format(this.value);
} catch (e) {
// XXX Report the error.
return this.value;
}
}
}
class FluentDateTime extends FluentType {
constructor(value, opts) {
super(new Date(value), opts);
}
toString(bundle) {
try {
const dtf = bundle._memoizeIntlObject(
Intl.DateTimeFormat, this.opts
);
return dtf.format(this.value);
} catch (e) {
// XXX Report the error.
return this.value;
}
}
}
/**
* @overview
*
* The FTL resolver ships with a number of functions built-in.
*
* Each function take two arguments:
* - args - an array of positional args
* - opts - an object of key-value args
*
* Arguments to functions are guaranteed to already be instances of
* `FluentType`. Functions must return `FluentType` objects as well.
*/
const builtins = {
"NUMBER": ([arg], opts) =>
new FluentNumber(arg.valueOf(), merge(arg.opts, opts)),
"DATETIME": ([arg], opts) =>
new FluentDateTime(arg.valueOf(), merge(arg.opts, opts)),
};
function merge(argopts, opts) {
return Object.assign({}, argopts, values(opts));
}
function values(opts) {
const unwrapped = {};
for (const [name, opt] of Object.entries(opts)) {
unwrapped[name] = opt.valueOf();
}
return unwrapped;
}
/* global Intl */
// Prevent expansion of too long placeables.
const MAX_PLACEABLE_LENGTH = 2500;
// Unicode bidi isolation characters.
const FSI = "\u2068";
const PDI = "\u2069";
// Helper: match a variant key to the given selector.
function match(bundle, selector, key) {
if (key === selector) {
// Both are strings.
return true;
}
// XXX Consider comparing options too, e.g. minimumFractionDigits.
if (key instanceof FluentNumber
&& selector instanceof FluentNumber
&& key.value === selector.value) {
return true;
}
if (selector instanceof FluentNumber && typeof key === "string") {
let category = bundle
._memoizeIntlObject(Intl.PluralRules, selector.opts)
.select(selector.value);
if (key === category) {
return true;
}
}
return false;
}
// Helper: resolve the default variant from a list of variants.
function getDefault(scope, variants, star) {
if (variants[star]) {
return Type(scope, variants[star]);
}
scope.errors.push(new RangeError("No default"));
return new FluentNone();
}
// Helper: resolve arguments to a call expression.
function getArguments(scope, args) {
const positional = [];
const named = {};
for (const arg of args) {
if (arg.type === "narg") {
named[arg.name] = Type(scope, arg.value);
} else {
positional.push(Type(scope, arg));
}
}
return [positional, named];
}
// Resolve an expression to a Fluent type.
function Type(scope, expr) {
// A fast-path for strings which are the most common case. Since they
// natively have the `toString` method they can be used as if they were
// a FluentType instance without incurring the cost of creating one.
if (typeof expr === "string") {
return scope.bundle._transform(expr);
}
// A fast-path for `FluentNone` which doesn't require any additional logic.
if (expr instanceof FluentNone) {
return expr;
}
// The Runtime AST (Entries) encodes patterns (complex strings with
// placeables) as Arrays.
if (Array.isArray(expr)) {
return Pattern(scope, expr);
}
switch (expr.type) {
case "str":
return expr.value;
case "num":
return new FluentNumber(expr.value, {
minimumFractionDigits: expr.precision,
});
case "var":
return VariableReference(scope, expr);
case "mesg":
return MessageReference(scope, expr);
case "term":
return TermReference(scope, expr);
case "func":
return FunctionReference(scope, expr);
case "select":
return SelectExpression(scope, expr);
case undefined: {
// If it's a node with a value, resolve the value.
if (expr.value !== null && expr.value !== undefined) {
return Type(scope, expr.value);
}
scope.errors.push(new RangeError("No value"));
return new FluentNone();
}
default:
return new FluentNone();
}
}
// Resolve a reference to a variable.
function VariableReference(scope, {name}) {
if (!scope.args || !scope.args.hasOwnProperty(name)) {
if (scope.insideTermReference === false) {
scope.errors.push(new ReferenceError(`Unknown variable: ${name}`));
}
return new FluentNone(`$${name}`);
}
const arg = scope.args[name];
// Return early if the argument already is an instance of FluentType.
if (arg instanceof FluentType) {
return arg;
}
// Convert the argument to a Fluent type.
switch (typeof arg) {
case "string":
return arg;
case "number":
return new FluentNumber(arg);
case "object":
if (arg instanceof Date) {
return new FluentDateTime(arg);
}
default:
scope.errors.push(
new TypeError(`Unsupported variable type: ${name}, ${typeof arg}`)
);
return new FluentNone(`$${name}`);
}
}
// Resolve a reference to another message.
function MessageReference(scope, {name, attr}) {
const message = scope.bundle._messages.get(name);
if (!message) {
const err = new ReferenceError(`Unknown message: ${name}`);
scope.errors.push(err);
return new FluentNone(name);
}
if (attr) {
const attribute = message.attrs && message.attrs[attr];
if (attribute) {
return Type(scope, attribute);
}
scope.errors.push(new ReferenceError(`Unknown attribute: ${attr}`));
return Type(scope, message);
}
return Type(scope, message);
}
// Resolve a call to a Term with key-value arguments.
function TermReference(scope, {name, attr, args}) {
const id = `-${name}`;
const term = scope.bundle._terms.get(id);
if (!term) {
const err = new ReferenceError(`Unknown term: ${id}`);
scope.errors.push(err);
return new FluentNone(id);
}
// Every TermReference has its own args.
const [, keyargs] = getArguments(scope, args);
const local = {...scope, args: keyargs, insideTermReference: true};
if (attr) {
const attribute = term.attrs && term.attrs[attr];
if (attribute) {
return Type(local, attribute);
}
scope.errors.push(new ReferenceError(`Unknown attribute: ${attr}`));
return Type(local, term);
}
return Type(local, term);
}
// Resolve a call to a Function with positional and key-value arguments.
function FunctionReference(scope, {name, args}) {
// Some functions are built-in. Others may be provided by the runtime via
// the `FluentBundle` constructor.
const func = scope.bundle._functions[name] || builtins[name];
if (!func) {
scope.errors.push(new ReferenceError(`Unknown function: ${name}()`));
return new FluentNone(`${name}()`);
}
if (typeof func !== "function") {
scope.errors.push(new TypeError(`Function ${name}() is not callable`));
return new FluentNone(`${name}()`);
}
try {
return func(...getArguments(scope, args));
} catch (e) {
// XXX Report errors.
return new FluentNone();
}
}
// Resolve a select expression to the member object.
function SelectExpression(scope, {selector, variants, star}) {
let sel = Type(scope, selector);
if (sel instanceof FluentNone) {
const variant = getDefault(scope, variants, star);
return Type(scope, variant);
}
// Match the selector against keys of each variant, in order.
for (const variant of variants) {
const key = Type(scope, variant.key);
if (match(scope.bundle, sel, key)) {
return Type(scope, variant);
}
}
const variant = getDefault(scope, variants, star);
return Type(scope, variant);
}
// Resolve a pattern (a complex string with placeables).
function Pattern(scope, ptn) {
if (scope.dirty.has(ptn)) {
scope.errors.push(new RangeError("Cyclic reference"));
return new FluentNone();
}
// Tag the pattern as dirty for the purpose of the current resolution.
scope.dirty.add(ptn);
const result = [];
// Wrap interpolations with Directional Isolate Formatting characters
// only when the pattern has more than one element.
const useIsolating = scope.bundle._useIsolating && ptn.length > 1;
for (const elem of ptn) {
if (typeof elem === "string") {
result.push(scope.bundle._transform(elem));
continue;
}
const part = Type(scope, elem).toString(scope.bundle);
if (useIsolating) {
result.push(FSI);
}
if (part.length > MAX_PLACEABLE_LENGTH) {
scope.errors.push(
new RangeError(
"Too many characters in placeable " +
`(${part.length}, max allowed is ${MAX_PLACEABLE_LENGTH})`
)
);
result.push(part.slice(MAX_PLACEABLE_LENGTH));
} else {
result.push(part);
}
if (useIsolating) {
result.push(PDI);
}
}
scope.dirty.delete(ptn);
return result.join("");
}
/**
* Format a translation into a string.
*
* @param {FluentBundle} bundle
* A FluentBundle instance which will be used to resolve the
* contextual information of the message.
* @param {Object} args
* List of arguments provided by the developer which can be accessed
* from the message.
* @param {Object} message
* An object with the Message to be resolved.
* @param {Array} errors
* An error array that any encountered errors will be appended to.
* @returns {FluentType}
*/
function resolve(bundle, args, message, errors = []) {
const scope = {
bundle, args, errors, dirty: new WeakSet(),
// TermReferences are resolved in a new scope.
insideTermReference: false,
};
return Type(scope, message).toString(bundle);
}
class FluentError extends Error {}
// This regex is used to iterate through the beginnings of messages and terms.
// With the /m flag, the ^ matches at the beginning of every line.
const RE_MESSAGE_START = /^(-?[a-zA-Z][\w-]*) *= */mg;
// Both Attributes and Variants are parsed in while loops. These regexes are
// used to break out of them.
const RE_ATTRIBUTE_START = /\.([a-zA-Z][\w-]*) *= */y;
const RE_VARIANT_START = /\*?\[/y;
const RE_NUMBER_LITERAL = /(-?[0-9]+(?:\.([0-9]+))?)/y;
const RE_IDENTIFIER = /([a-zA-Z][\w-]*)/y;
const RE_REFERENCE = /([$-])?([a-zA-Z][\w-]*)(?:\.([a-zA-Z][\w-]*))?/y;
const RE_FUNCTION_NAME = /^[A-Z][A-Z0-9_-]*$/;
// A "run" is a sequence of text or string literal characters which don't
// require any special handling. For TextElements such special characters are: {
// (starts a placeable), and line breaks which require additional logic to check
// if the next line is indented. For StringLiterals they are: \ (starts an
// escape sequence), " (ends the literal), and line breaks which are not allowed
// in StringLiterals. Note that string runs may be empty; text runs may not.
const RE_TEXT_RUN = /([^{}\n\r]+)/y;
const RE_STRING_RUN = /([^\\"\n\r]*)/y;
// Escape sequences.
const RE_STRING_ESCAPE = /\\([\\"])/y;
const RE_UNICODE_ESCAPE = /\\u([a-fA-F0-9]{4})|\\U([a-fA-F0-9]{6})/y;
// Used for trimming TextElements and indents.
const RE_LEADING_NEWLINES = /^\n+/;
const RE_TRAILING_SPACES = / +$/;
// Used in makeIndent to strip spaces from blank lines and normalize CRLF to LF.
const RE_BLANK_LINES = / *\r?\n/g;
// Used in makeIndent to measure the indentation.
const RE_INDENT = /( *)$/;
// Common tokens.
const TOKEN_BRACE_OPEN = /{\s*/y;
const TOKEN_BRACE_CLOSE = /\s*}/y;
const TOKEN_BRACKET_OPEN = /\[\s*/y;
const TOKEN_BRACKET_CLOSE = /\s*] */y;
const TOKEN_PAREN_OPEN = /\s*\(\s*/y;
const TOKEN_ARROW = /\s*->\s*/y;
const TOKEN_COLON = /\s*:\s*/y;
// Note the optional comma. As a deviation from the Fluent EBNF, the parser
// doesn't enforce commas between call arguments.
const TOKEN_COMMA = /\s*,?\s*/y;
const TOKEN_BLANK = /\s+/y;
// Maximum number of placeables in a single Pattern to protect against Quadratic
// Blowup attacks. See https://msdn.microsoft.com/en-us/magazine/ee335713.aspx.
const MAX_PLACEABLES = 100;
/**
* Fluent Resource is a structure storing a map of parsed localization entries.
*/
class FluentResource extends Map {
/**
* Create a new FluentResource from Fluent code.
*/
static fromString(source) {
RE_MESSAGE_START.lastIndex = 0;
let resource = new this();
let cursor = 0;
// Iterate over the beginnings of messages and terms to efficiently skip
// comments and recover from errors.
while (true) {
let next = RE_MESSAGE_START.exec(source);
if (next === null) {
break;
}
cursor = RE_MESSAGE_START.lastIndex;
try {
resource.set(next[1], parseMessage());
} catch (err) {
if (err instanceof FluentError) {
// Don't report any Fluent syntax errors. Skip directly to the
// beginning of the next message or term.
continue;
}
throw err;
}
}
return resource;
// The parser implementation is inlined below for performance reasons.
// The parser focuses on minimizing the number of false negatives at the
// expense of increasing the risk of false positives. In other words, it
// aims at parsing valid Fluent messages with a success rate of 100%, but it
// may also parse a few invalid messages which the reference parser would
// reject. The parser doesn't perform any validation and may produce entries
// which wouldn't make sense in the real world. For best results users are
// advised to validate translations with the fluent-syntax parser
// pre-runtime.
// The parser makes an extensive use of sticky regexes which can be anchored
// to any offset of the source string without slicing it. Errors are thrown
// to bail out of parsing of ill-formed messages.
function test(re) {
re.lastIndex = cursor;
return re.test(source);
}
// Advance the cursor by the char if it matches. May be used as a predicate
// (was the match found?) or, if errorClass is passed, as an assertion.
function consumeChar(char, errorClass) {
if (source[cursor] === char) {
cursor++;
return true;
}
if (errorClass) {
throw new errorClass(`Expected ${char}`);
}
return false;
}
// Advance the cursor by the token if it matches. May be used as a predicate
// (was the match found?) or, if errorClass is passed, as an assertion.
function consumeToken(re, errorClass) {
if (test(re)) {
cursor = re.lastIndex;
return true;
}
if (errorClass) {
throw new errorClass(`Expected ${re.toString()}`);
}
return false;
}
// Execute a regex, advance the cursor, and return all capture groups.
function match(re) {
re.lastIndex = cursor;
let result = re.exec(source);
if (result === null) {
throw new FluentError(`Expected ${re.toString()}`);
}
cursor = re.lastIndex;
return result;
}
// Execute a regex, advance the cursor, and return the capture group.
function match1(re) {
return match(re)[1];
}
function parseMessage() {
let value = parsePattern();
let attrs = parseAttributes();
if (attrs === null) {
if (value === null) {
throw new FluentError("Expected message value or attributes");
}
return value;
}
return {value, attrs};
}
function parseAttributes() {
let attrs = {};
while (test(RE_ATTRIBUTE_START)) {
let name = match1(RE_ATTRIBUTE_START);
let value = parsePattern();
if (value === null) {
throw new FluentError("Expected attribute value");
}
attrs[name] = value;
}
return Object.keys(attrs).length > 0 ? attrs : null;
}
function parsePattern() {
// First try to parse any simple text on the same line as the id.
if (test(RE_TEXT_RUN)) {
var first = match1(RE_TEXT_RUN);
}
// If there's a placeable on the first line, parse a complex pattern.
if (source[cursor] === "{" || source[cursor] === "}") {
// Re-use the text parsed above, if possible.
return parsePatternElements(first ? [first] : [], Infinity);
}
// RE_TEXT_VALUE stops at newlines. Only continue parsing the pattern if
// what comes after the newline is indented.
let indent = parseIndent();
if (indent) {
if (first) {
// If there's text on the first line, the blank block is part of the
// translation content in its entirety.
return parsePatternElements([first, indent], indent.length);
}
// Otherwise, we're dealing with a block pattern, i.e. a pattern which
// starts on a new line. Discrad the leading newlines but keep the
// inline indent; it will be used by the dedentation logic.
indent.value = trim(indent.value, RE_LEADING_NEWLINES);
return parsePatternElements([indent], indent.length);
}
if (first) {
// It was just a simple inline text after all.
return trim(first, RE_TRAILING_SPACES);
}
return null;
}
// Parse a complex pattern as an array of elements.
function parsePatternElements(elements = [], commonIndent) {
let placeableCount = 0;
while (true) {
if (test(RE_TEXT_RUN)) {
elements.push(match1(RE_TEXT_RUN));
continue;
}
if (source[cursor] === "{") {
if (++placeableCount > MAX_PLACEABLES) {
throw new FluentError("Too many placeables");
}
elements.push(parsePlaceable());
continue;
}
if (source[cursor] === "}") {
throw new FluentError("Unbalanced closing brace");
}
let indent = parseIndent();
if (indent) {
elements.push(indent);
commonIndent = Math.min(commonIndent, indent.length);
continue;
}
break;
}
let lastIndex = elements.length - 1;
// Trim the trailing spaces in the last element if it's a TextElement.
if (typeof elements[lastIndex] === "string") {
elements[lastIndex] = trim(elements[lastIndex], RE_TRAILING_SPACES);
}
let baked = [];
for (let element of elements) {
if (element.type === "indent") {
// Dedent indented lines by the maximum common indent.
element = element.value.slice(0, element.value.length - commonIndent);
} else if (element.type === "str") {
// Optimize StringLiterals into their value.
element = element.value;
}
if (element) {
baked.push(element);
}
}
return baked;
}
function parsePlaceable() {
consumeToken(TOKEN_BRACE_OPEN, FluentError);
let selector = parseInlineExpression();
if (consumeToken(TOKEN_BRACE_CLOSE)) {
return selector;
}
if (consumeToken(TOKEN_ARROW)) {
let variants = parseVariants();
consumeToken(TOKEN_BRACE_CLOSE, FluentError);
return {type: "select", selector, ...variants};
}
throw new FluentError("Unclosed placeable");
}
function parseInlineExpression() {
if (source[cursor] === "{") {
// It's a nested placeable.
return parsePlaceable();
}
if (test(RE_REFERENCE)) {
let [, sigil, name, attr = null] = match(RE_REFERENCE);
if (sigil === "$") {
return {type: "var", name};
}
if (consumeToken(TOKEN_PAREN_OPEN)) {
let args = parseArguments();
if (sigil === "-") {
// A parameterized term: -term(...).
return {type: "term", name, attr, args};
}
if (RE_FUNCTION_NAME.test(name)) {
return {type: "func", name, args};
}
throw new FluentError("Function names must be all upper-case");
}
if (sigil === "-") {
// A non-parameterized term: -term.
return {type: "term", name, attr, args: []};
}
return {type: "mesg", name, attr};
}
return parseLiteral();
}
function parseArguments() {
let args = [];
while (true) {
switch (source[cursor]) {
case ")": // End of the argument list.
cursor++;
return args;
case undefined: // EOF
throw new FluentError("Unclosed argument list");
}
args.push(parseArgument());
// Commas between arguments are treated as whitespace.
consumeToken(TOKEN_COMMA);
}
}
function parseArgument() {
let expr = parseInlineExpression();
if (expr.type !== "mesg") {
return expr;
}
if (consumeToken(TOKEN_COLON)) {
// The reference is the beginning of a named argument.
return {type: "narg", name: expr.name, value: parseLiteral()};
}
// It's a regular message reference.
return expr;
}
function parseVariants() {
let variants = [];
let count = 0;
let star;
while (test(RE_VARIANT_START)) {
if (consumeChar("*")) {
star = count;
}
let key = parseVariantKey();
let value = parsePattern();
if (value === null) {
throw new FluentError("Expected variant value");
}
variants[count++] = {key, value};
}
if (count === 0) {
return null;
}
if (star === undefined) {
throw new FluentError("Expected default variant");
}
return {variants, star};
}
function parseVariantKey() {
consumeToken(TOKEN_BRACKET_OPEN, FluentError);
let key = test(RE_NUMBER_LITERAL)
? parseNumberLiteral()
: match1(RE_IDENTIFIER);
consumeToken(TOKEN_BRACKET_CLOSE, FluentError);
return key;
}
function parseLiteral() {
if (test(RE_NUMBER_LITERAL)) {
return parseNumberLiteral();
}
if (source[cursor] === "\"") {
return parseStringLiteral();
}
throw new FluentError("Invalid expression");
}
function parseNumberLiteral() {
let [, value, fraction = ""] = match(RE_NUMBER_LITERAL);
let precision = fraction.length;
return {type: "num", value: parseFloat(value), precision};
}
function parseStringLiteral() {
consumeChar("\"", FluentError);
let value = "";
while (true) {
value += match1(RE_STRING_RUN);
if (source[cursor] === "\\") {
value += parseEscapeSequence();
continue;
}
if (consumeChar("\"")) {
return {type: "str", value};
}
// We've reached an EOL of EOF.
throw new FluentError("Unclosed string literal");
}
}
// Unescape known escape sequences.
function parseEscapeSequence() {
if (test(RE_STRING_ESCAPE)) {
return match1(RE_STRING_ESCAPE);
}
if (test(RE_UNICODE_ESCAPE)) {
let [, codepoint4, codepoint6] = match(RE_UNICODE_ESCAPE);
let codepoint = parseInt(codepoint4 || codepoint6, 16);
return codepoint <= 0xD7FF || 0xE000 <= codepoint
// It's a Unicode scalar value.
? String.fromCodePoint(codepoint)
// Lonely surrogates can cause trouble when the parsing result is
// saved using UTF-8. Use U+FFFD REPLACEMENT CHARACTER instead.
: "<22>";
}
throw new FluentError("Unknown escape sequence");
}
// Parse blank space. Return it if it looks like indent before a pattern
// line. Skip it othwerwise.
function parseIndent() {
let start = cursor;
consumeToken(TOKEN_BLANK);
// Check the first non-blank character after the indent.
switch (source[cursor]) {
case ".":
case "[":
case "*":
case "}":
case undefined: // EOF
// A special character. End the Pattern.
return false;
case "{":
// Placeables don't require indentation (in EBNF: block-placeable).
// Continue the Pattern.
return makeIndent(source.slice(start, cursor));
}
// If the first character on the line is not one of the special characters
// listed above, it's a regular text character. Check if there's at least
// one space of indent before it.
if (source[cursor - 1] === " ") {
// It's an indented text character (in EBNF: indented-char). Continue
// the Pattern.
return makeIndent(source.slice(start, cursor));
}
// A not-indented text character is likely the identifier of the next
// message. End the Pattern.
return false;
}
// Trim blanks in text according to the given regex.
function trim(text, re) {
return text.replace(re, "");
}
// Normalize a blank block and extract the indent details.
function makeIndent(blank) {
let value = blank.replace(RE_BLANK_LINES, "\n");
let length = RE_INDENT.exec(blank)[1].length;
return {type: "indent", value, length};
}
}
}
/**
* Message bundles are single-language stores of translations. They are
* responsible for parsing translation resources in the Fluent syntax and can
* format translation units (entities) to strings.
*
* Always use `FluentBundle.format` to retrieve translation units from a
* bundle. Translations can contain references to other entities or variables,
* conditional logic in form of select expressions, traits which describe their
* grammatical features, and can use Fluent builtins which make use of the
* `Intl` formatters to format numbers, dates, lists and more into the
* bundle's language. See the documentation of the Fluent syntax for more
* information.
*/
class FluentBundle {
/**
* Create an instance of `FluentBundle`.
*
* The `locales` argument is used to instantiate `Intl` formatters used by
* translations. The `options` object can be used to configure the bundle.
*
* Examples:
*
* const bundle = new FluentBundle(locales);
*
* const bundle = new FluentBundle(locales, { useIsolating: false });
*
* const bundle = new FluentBundle(locales, {
* 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.
* Default: true
*
* - `transform` - a function used to transform string parts of patterns.
*
* @param {string|Array<string>} locales - Locale or locales of the bundle
* @param {Object} [options]
* @returns {FluentBundle}
*/
constructor(locales, {
functions = {},
useIsolating = true,
transform = v => v,
} = {}) {
this.locales = Array.isArray(locales) ? locales : [locales];
this._terms = new Map();
this._messages = new Map();
this._functions = functions;
this._useIsolating = useIsolating;
this._transform = transform;
this._intls = new WeakMap();
}
/*
* Return an iterator over public `[id, message]` pairs.
*
* @returns {Iterator}
*/
get messages() {
return this._messages[Symbol.iterator]();
}
/*
* Check if a message is present in the bundle.
*
* @param {string} id - The identifier of the message to check.
* @returns {bool}
*/
hasMessage(id) {
return this._messages.has(id);
}
/*
* Return the internal representation of a message.
*
* The internal representation should only be used as an argument to
* `FluentBundle.format`.
*
* @param {string} id - The identifier of the message to check.
* @returns {Any}
*/
getMessage(id) {
return this._messages.get(id);
}
/**
* Add a translation resource to the bundle.
*
* The translation resource must use the Fluent syntax. It will be parsed by
* the bundle and each translation unit (message) will be available in the
* bundle by its identifier.
*
* bundle.addMessages('foo = Foo');
* bundle.getMessage('foo');
*
* // Returns a raw representation of the 'foo' message.
*
* bundle.addMessages('bar = Bar');
* bundle.addMessages('bar = Newbar', { allowOverrides: true });
* bundle.getMessage('bar');
*
* // Returns a raw representation of the 'bar' message: Newbar.
*
* Parsed entities should be formatted with the `format` method in case they
* contain logic (references, select expressions etc.).
*
* Available options:
*
* - `allowOverrides` - boolean specifying whether it's allowed to override
* an existing message or term with a new value.
* Default: false
*
* @param {string} source - Text resource with translations.
* @param {Object} [options]
* @returns {Array<Error>}
*/
addMessages(source, options) {
const res = FluentResource.fromString(source);
return this.addResource(res, options);
}
/**
* Add a translation resource to the bundle.
*
* The translation resource must be an instance of FluentResource,
* e.g. parsed by `FluentResource.fromString`.
*
* let res = FluentResource.fromString("foo = Foo");
* bundle.addResource(res);
* bundle.getMessage('foo');
*
* // Returns a raw representation of the 'foo' message.
*
* let res = FluentResource.fromString("bar = Bar");
* bundle.addResource(res);
* res = FluentResource.fromString("bar = Newbar");
* bundle.addResource(res, { allowOverrides: true });
* bundle.getMessage('bar');
*
* // Returns a raw representation of the 'bar' message: Newbar.
*
* Parsed entities should be formatted with the `format` method in case they
* contain logic (references, select expressions etc.).
*
* Available options:
*
* - `allowOverrides` - boolean specifying whether it's allowed to override
* an existing message or term with a new value.
* Default: false
*
* @param {FluentResource} res - FluentResource object.
* @param {Object} [options]
* @returns {Array<Error>}
*/
addResource(res, {
allowOverrides = false,
} = {}) {
const errors = [];
for (const [id, value] of res) {
if (id.startsWith("-")) {
// Identifiers starting with a dash (-) define terms. Terms are private
// and cannot be retrieved from FluentBundle.
if (allowOverrides === false && this._terms.has(id)) {
errors.push(`Attempt to override an existing term: "${id}"`);
continue;
}
this._terms.set(id, value);
} else {
if (allowOverrides === false && this._messages.has(id)) {
errors.push(`Attempt to override an existing message: "${id}"`);
continue;
}
this._messages.set(id, value);
}
}
return errors;
}
/**
* Format a message to a string or null.
*
* Format a raw `message` from the bundle into a string (or a null if it has
* a null value). `args` will be used to resolve references to variables
* passed as arguments to 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 = [];
* bundle.addMessages('hello = Hello, { $name }!');
* const hello = bundle.getMessage('hello');
* bundle.format(hello, { name: 'Jane' }, errors);
*
* // Returns 'Hello, Jane!' and `errors` is empty.
*
* bundle.format(hello, undefined, errors);
*
* // Returns 'Hello, name!' and `errors` is now:
*
* [<ReferenceError: Unknown variable: name>]
*
* @param {Object | string} message
* @param {Object | undefined} args
* @param {Array} errors
* @returns {?string}
*/
format(message, args, errors) {
// optimize entities which are simple strings with no attributes
if (typeof message === "string") {
return this._transform(message);
}
// optimize entities with null values
if (message === null || message.value === null) {
return null;
}
// optimize simple-string entities with attributes
if (typeof message.value === "string") {
return this._transform(message.value);
}
return resolve(this, args, message, errors);
}
_memoizeIntlObject(ctor, opts) {
const cache = this._intls.get(ctor) || {};
const id = JSON.stringify(opts);
if (!cache[id]) {
cache[id] = new ctor(this.locales, opts);
this._intls.set(ctor, cache);
}
return cache[id];
}
}
/*
* @module fluent
* @overview
*
* `fluent` is a JavaScript implementation of Project Fluent, a localization
* framework designed to unleash the expressive power of the natural language.
*
*/
this.EXPORTED_SYMBOLS = [
...Object.keys({
FluentBundle,
FluentResource,
FluentError,
FluentType,
FluentNumber,
FluentDateTime,
}),
];