@@ -7,9 +7,7 @@ import { NUMBER, DATETIME } from "./builtins.js";
77import { getMemoizerForLocale , IntlCache } from "./memoizer.js" ;
88
99export type TextTransform = ( text : string ) => string ;
10-
11- type NativeValue = string | number | Date ;
12- export type FluentVariable = FluentValue | NativeValue ;
10+ export type FluentVariable = FluentValue | string | number | Date ;
1311
1412/**
1513 * Message bundles are single-language stores of translation resources. They are
@@ -18,41 +16,38 @@ export type FluentVariable = FluentValue | NativeValue;
1816export class FluentBundle {
1917 public locales : Array < string > ;
2018
19+ /** @ignore */
2120 public _terms : Map < string , Term > = new Map ( ) ;
21+ /** @ignore */
2222 public _messages : Map < string , Message > = new Map ( ) ;
23+ /** @ignore */
2324 public _functions : Record < string , FluentFunction > ;
25+ /** @ignore */
2426 public _useIsolating : boolean ;
27+ /** @ignore */
2528 public _transform : TextTransform ;
29+ /** @ignore */
2630 public _intls : IntlCache ;
2731
2832 /**
2933 * Create an instance of `FluentBundle`.
3034 *
31- * The `locales` argument is used to instantiate `Intl` formatters used by
32- * translations. The `options` object can be used to configure the bundle.
33- *
34- * Examples:
35- *
36- * let bundle = new FluentBundle(["en-US", "en"]);
37- *
38- * let bundle = new FluentBundle(locales, {useIsolating: false});
35+ * @example
36+ * ```js
37+ * let bundle = new FluentBundle(["en-US", "en"]);
3938 *
40- * let bundle = new FluentBundle(locales, {
41- * useIsolating: true,
42- * functions: {
43- * NODE_ENV: () => process.env.NODE_ENV
44- * }
45- * });
39+ * let bundle = new FluentBundle(locales, {useIsolating: false});
4640 *
47- * Available options:
41+ * let bundle = new FluentBundle(locales, {
42+ * useIsolating: true,
43+ * functions: {
44+ * NODE_ENV: () => process.env.NODE_ENV
45+ * }
46+ * });
47+ * ```
4848 *
49- * - `functions` - an object of additional functions available to
50- * translations as builtins.
51- *
52- * - `useIsolating` - boolean specifying whether to use Unicode isolation
53- * marks (FSI, PDI) for bidi interpolations. Default: `true`.
54- *
55- * - `transform` - a function used to transform string parts of patterns.
49+ * @param locales - Used to instantiate `Intl` formatters used by translations.
50+ * @param options - Optional configuration for the bundle.
5651 */
5752 constructor (
5853 locales : string | Array < string > ,
@@ -61,8 +56,15 @@ export class FluentBundle {
6156 useIsolating = true ,
6257 transform = ( v : string ) : string => v ,
6358 } : {
59+ /** Additional functions available to translations as builtins. */
6460 functions ?: Record < string , FluentFunction > ;
61+ /**
62+ * Whether to use Unicode isolation marks (FSI, PDI) for bidi interpolations.
63+ *
64+ * Default: `true`.
65+ */
6566 useIsolating ?: boolean ;
67+ /** A function used to transform string parts of patterns. */
6668 transform ?: TextTransform ;
6769 } = { }
6870 ) {
@@ -102,24 +104,30 @@ export class FluentBundle {
102104 /**
103105 * Add a translation resource to the bundle.
104106 *
105- * The translation resource must be an instance of `FluentResource`.
106- *
107- * let res = new FluentResource("foo = Foo");
108- * bundle.addResource(res);
109- * bundle.getMessage("foo");
110- * // → {value: .., attributes: {..}}
111- *
112- * Available options:
107+ * @example
108+ * ```js
109+ * let res = new FluentResource("foo = Foo");
110+ * bundle.addResource(res);
111+ * bundle.getMessage("foo");
112+ * // → {value: .., attributes: {..}}
113+ * ```
113114 *
114- * - `allowOverrides` - boolean specifying whether it's allowed to override
115- * an existing message or term with a new value. Default: `false`.
116- *
117- * @param res - FluentResource object.
118- * @param options
115+ * @param res
116+ * @param options
119117 */
120118 addResource (
121119 res : FluentResource ,
122- { allowOverrides = false } : { allowOverrides ?: boolean } = { }
120+ {
121+ allowOverrides = false ,
122+ } : {
123+ /**
124+ * Boolean specifying whether it's allowed to override
125+ * an existing message or term with a new value.
126+ *
127+ * Default: `false`.
128+ */
129+ allowOverrides ?: boolean ;
130+ } = { }
123131 ) : Array < Error > {
124132 const errors = [ ] ;
125133
@@ -160,21 +168,24 @@ export class FluentBundle {
160168 * reasons, the encountered errors are not returned but instead are appended
161169 * to the `errors` array passed as the third argument.
162170 *
163- * let errors = [];
164- * bundle.addResource(
165- * new FluentResource("hello = Hello, {$name}!"));
166- *
167- * let hello = bundle.getMessage("hello");
168- * if (hello.value) {
169- * bundle.formatPattern(hello.value, {name: "Jane"}, errors);
170- * // Returns "Hello, Jane!" and `errors` is empty.
171- *
172- * bundle.formatPattern(hello.value, undefined, errors);
173- * // Returns "Hello, {$name}!" and `errors` is now:
174- * // [<ReferenceError: Unknown variable: name>]
175- * }
176- *
177171 * If `errors` is omitted, the first encountered error will be thrown.
172+ *
173+ * @example
174+ * ```js
175+ * let errors = [];
176+ * bundle.addResource(
177+ * new FluentResource("hello = Hello, {$name}!"));
178+ *
179+ * let hello = bundle.getMessage("hello");
180+ * if (hello.value) {
181+ * bundle.formatPattern(hello.value, {name: "Jane"}, errors);
182+ * // Returns "Hello, Jane!" and `errors` is empty.
183+ *
184+ * bundle.formatPattern(hello.value, undefined, errors);
185+ * // Returns "Hello, {$name}!" and `errors` is now:
186+ * // [<ReferenceError: Unknown variable: name>]
187+ * }
188+ * ```
178189 */
179190 formatPattern (
180191 pattern : Pattern ,
0 commit comments