@worldware/msg 0.8.1 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (35) hide show
  1. package/dist/{chunk-NWJ7MVVV.mjs → chunk-DJFPVXQ5.mjs} +15 -0
  2. package/dist/{chunk-HCR2UNSE.mjs → chunk-F3VAAZJZ.mjs} +39 -0
  3. package/dist/{chunk-X6CRKSNU.mjs → chunk-IMOOTZIK.mjs} +68 -1
  4. package/dist/chunk-PU7ZZ5XH.mjs +13 -0
  5. package/dist/classes/MsgInterface/MsgInterface.d.cts +24 -1
  6. package/dist/classes/MsgInterface/MsgInterface.d.ts +24 -1
  7. package/dist/classes/MsgMessage/MsgMessage.cjs +39 -0
  8. package/dist/classes/MsgMessage/MsgMessage.d.cts +51 -0
  9. package/dist/classes/MsgMessage/MsgMessage.d.ts +51 -0
  10. package/dist/classes/MsgMessage/MsgMessage.mjs +1 -1
  11. package/dist/classes/MsgProject/MsgProject.cjs +15 -0
  12. package/dist/classes/MsgProject/MsgProject.d.cts +1 -1
  13. package/dist/classes/MsgProject/MsgProject.d.ts +1 -1
  14. package/dist/classes/MsgProject/MsgProject.mjs +1 -1
  15. package/dist/classes/MsgResource/MsgResource.cjs +106 -0
  16. package/dist/classes/MsgResource/MsgResource.d.cts +124 -2
  17. package/dist/classes/MsgResource/MsgResource.d.ts +124 -2
  18. package/dist/classes/MsgResource/MsgResource.mjs +2 -2
  19. package/dist/classes/index.cjs +121 -0
  20. package/dist/classes/index.d.cts +2 -2
  21. package/dist/classes/index.d.ts +2 -2
  22. package/dist/classes/index.mjs +5 -5
  23. package/dist/index.cjs +121 -0
  24. package/dist/index.d.cts +2 -2
  25. package/dist/index.d.ts +2 -2
  26. package/dist/index.mjs +5 -5
  27. package/dist/lib/index.cjs +40 -0
  28. package/dist/lib/index.d.cts +1 -0
  29. package/dist/lib/index.d.ts +1 -0
  30. package/dist/lib/index.mjs +8 -0
  31. package/dist/lib/lang-utils.cjs +38 -0
  32. package/dist/lib/lang-utils.d.cts +14 -0
  33. package/dist/lib/lang-utils.d.ts +14 -0
  34. package/dist/lib/lang-utils.mjs +8 -0
  35. package/package.json +1 -1
@@ -2,39 +2,90 @@ import * as messageformat from 'messageformat';
2
2
  import { MessageFormatOptions } from 'messageformat';
3
3
  import { MsgInterface, MsgAttributes, MsgNote } from '../MsgInterface/MsgInterface.js';
4
4
 
5
+ /**
6
+ * Plain data used to create a {@link MsgMessage}.
7
+ */
5
8
  type MsgMessageData = {
9
+ /** Unique key that identifies this message within a resource. */
6
10
  key: string;
11
+ /** The message string, possibly in MessageFormat syntax. */
7
12
  value: string;
13
+ /** Optional locale and formatting metadata. */
8
14
  attributes?: MsgAttributes;
15
+ /** Optional notes for translators and tooling. */
9
16
  notes?: MsgNote[];
10
17
  };
18
+ /**
19
+ * A single localizable message with a key, value, attributes, and notes.
20
+ *
21
+ * Supports MessageFormat 1, MessageFormat 2, and unformatted (`NONE`) strings.
22
+ */
11
23
  declare class MsgMessage implements MsgInterface {
12
24
  private _key;
13
25
  private _value;
14
26
  private _mf?;
15
27
  private _attributes;
16
28
  private _notes;
29
+ /**
30
+ * Creates a message from its parts. Prefer {@link MsgMessage.create}.
31
+ */
17
32
  private constructor();
33
+ /**
34
+ * Builds a message from {@link MsgMessageData}.
35
+ */
18
36
  static create(data: MsgMessageData): MsgMessage;
37
+ /** Unique key that identifies this message within a resource. */
19
38
  get key(): string;
39
+ /** The message string, possibly in MessageFormat syntax. */
20
40
  get value(): string;
41
+ /** Locale and formatting metadata for this message. */
21
42
  get attributes(): MsgAttributes;
43
+ /** Notes attached to this message for translators and tooling. */
22
44
  get notes(): MsgNote[];
45
+ /**
46
+ * Appends a note to this message.
47
+ */
23
48
  addNote(note: MsgNote): void;
24
49
  /**
25
50
  * The message's resolved format, defaulting to MF2 when not set or inherited.
26
51
  */
27
52
  private resolveFormat;
53
+ /**
54
+ * Returns a cached MessageFormat formatter for this message's value.
55
+ */
28
56
  private getFormatter;
57
+ /**
58
+ * Formats the message with the given placeholder data.
59
+ *
60
+ * For `NONE` format messages, returns the raw value unchanged.
61
+ */
29
62
  format(data: Record<string, any>, options?: MessageFormatOptions): string;
63
+ /**
64
+ * Formats the message into structured parts with the given placeholder data.
65
+ *
66
+ * For `NONE` format messages, returns a single text part with the raw value.
67
+ */
30
68
  formatToParts(data: Record<string, any>, options?: MessageFormatOptions): messageformat.MessagePart<never>[];
69
+ /**
70
+ * Returns a plain data object for this message.
71
+ *
72
+ * @param stripNotes - When true, notes are omitted from the result.
73
+ */
31
74
  getData(stripNotes?: boolean): {
32
75
  key: string;
33
76
  value: string;
34
77
  attributes: MsgAttributes;
35
78
  notes: MsgNote[] | undefined;
36
79
  };
80
+ /**
81
+ * Returns the message value as a string.
82
+ */
37
83
  toString(): string;
84
+ /**
85
+ * Serializes this message to a formatted JSON string.
86
+ *
87
+ * @param stripNotes - When true, notes are omitted from the serialized data.
88
+ */
38
89
  toJSON(stripNotes?: boolean): string;
39
90
  }
40
91
 
@@ -1,6 +1,6 @@
1
1
  import {
2
2
  MsgMessage
3
- } from "../../chunk-HCR2UNSE.mjs";
3
+ } from "../../chunk-F3VAAZJZ.mjs";
4
4
  import "../../chunk-XQVALCKX.mjs";
5
5
  export {
6
6
  MsgMessage
@@ -41,24 +41,36 @@ var defaultLocalesSettings = {
41
41
  }
42
42
  };
43
43
  var MsgProject = class _MsgProject {
44
+ /** Project name, version, and default format. */
44
45
  _project;
46
+ /** Source, pseudo, and target locale settings. */
45
47
  _locales;
48
+ /** Function used to load translations for a locale. */
46
49
  _loader;
50
+ /**
51
+ * Builds a project from {@link MsgProjectData}.
52
+ */
47
53
  static create(data) {
48
54
  const { project, locales, loader } = data;
49
55
  return new _MsgProject(project, locales, loader);
50
56
  }
57
+ /**
58
+ * Creates a project from its settings and loader. Prefer {@link MsgProject.create}.
59
+ */
51
60
  constructor(projectSettings, localesSettings, loader) {
52
61
  this._project = { ...defaultProjectSettings, ...projectSettings };
53
62
  this._locales = { ...defaultLocalesSettings, ...localesSettings };
54
63
  this._loader = loader;
55
64
  }
65
+ /** Project name, version, and default format. */
56
66
  get project() {
57
67
  return this._project;
58
68
  }
69
+ /** Source, pseudo, and target locale settings. */
59
70
  get locales() {
60
71
  return this._locales;
61
72
  }
73
+ /** Function used to load translations for a locale. */
62
74
  get loader() {
63
75
  return this._loader;
64
76
  }
@@ -69,6 +81,9 @@ var MsgProject = class _MsgProject {
69
81
  get format() {
70
82
  return this._project.format ?? MSG_DEFAULT_FORMAT;
71
83
  }
84
+ /**
85
+ * Returns the translation load chain for a locale, or `undefined` if unsupported.
86
+ */
72
87
  getTargetLocale(locale) {
73
88
  return this._locales.targetLocales[locale];
74
89
  }
@@ -1,4 +1,4 @@
1
- export { M as MsgProject, a as MsgProjectData, b as MsgTranslationLoader } from '../MsgResource/MsgResource.cjs';
1
+ export { M as MsgLocalesSettings, a as MsgProject, b as MsgProjectData, c as MsgProjectSettings, d as MsgTargetLocalesSettings, e as MsgTranslationLoader } from '../MsgResource/MsgResource.cjs';
2
2
  import '../MsgInterface/MsgInterface.cjs';
3
3
  import '../MsgMessage/MsgMessage.cjs';
4
4
  import 'messageformat';
@@ -1,4 +1,4 @@
1
- export { M as MsgProject, a as MsgProjectData, b as MsgTranslationLoader } from '../MsgResource/MsgResource.js';
1
+ export { M as MsgLocalesSettings, a as MsgProject, b as MsgProjectData, c as MsgProjectSettings, d as MsgTargetLocalesSettings, e as MsgTranslationLoader } from '../MsgResource/MsgResource.js';
2
2
  import '../MsgInterface/MsgInterface.js';
3
3
  import '../MsgMessage/MsgMessage.js';
4
4
  import 'messageformat';
@@ -1,6 +1,6 @@
1
1
  import {
2
2
  MsgProject
3
- } from "../../chunk-NWJ7MVVV.mjs";
3
+ } from "../../chunk-DJFPVXQ5.mjs";
4
4
  import "../../chunk-XQVALCKX.mjs";
5
5
  export {
6
6
  MsgProject
@@ -45,6 +45,9 @@ var MsgMessage = class _MsgMessage {
45
45
  _mf;
46
46
  _attributes;
47
47
  _notes = [];
48
+ /**
49
+ * Creates a message from its parts. Prefer {@link MsgMessage.create}.
50
+ */
48
51
  constructor(key, value, attributes, notes) {
49
52
  this._key = key;
50
53
  this._value = value;
@@ -53,23 +56,33 @@ var MsgMessage = class _MsgMessage {
53
56
  notes.forEach((note) => this.addNote(note));
54
57
  }
55
58
  }
59
+ /**
60
+ * Builds a message from {@link MsgMessageData}.
61
+ */
56
62
  static create(data) {
57
63
  const { key, value, attributes, notes } = data;
58
64
  const message = new _MsgMessage(key, value, attributes, notes);
59
65
  return message;
60
66
  }
67
+ /** Unique key that identifies this message within a resource. */
61
68
  get key() {
62
69
  return this._key;
63
70
  }
71
+ /** The message string, possibly in MessageFormat syntax. */
64
72
  get value() {
65
73
  return this._value;
66
74
  }
75
+ /** Locale and formatting metadata for this message. */
67
76
  get attributes() {
68
77
  return this._attributes;
69
78
  }
79
+ /** Notes attached to this message for translators and tooling. */
70
80
  get notes() {
71
81
  return this._notes;
72
82
  }
83
+ /**
84
+ * Appends a note to this message.
85
+ */
73
86
  addNote(note) {
74
87
  this.notes.push(note);
75
88
  }
@@ -79,24 +92,42 @@ var MsgMessage = class _MsgMessage {
79
92
  resolveFormat() {
80
93
  return this.attributes.format ?? MSG_DEFAULT_FORMAT;
81
94
  }
95
+ /**
96
+ * Returns a cached MessageFormat formatter for this message's value.
97
+ */
82
98
  getFormatter(options) {
83
99
  if (!this._mf) {
84
100
  this._mf = this.resolveFormat() === "MF1" ? (0, import_icu_messageformat_1.mf1ToMessage)(this.attributes.lang, this.value, options) : new import_messageformat.MessageFormat(this.attributes.lang, this.value, options);
85
101
  }
86
102
  return this._mf;
87
103
  }
104
+ /**
105
+ * Formats the message with the given placeholder data.
106
+ *
107
+ * For `NONE` format messages, returns the raw value unchanged.
108
+ */
88
109
  format(data, options) {
89
110
  if (this.resolveFormat() === "NONE") {
90
111
  return this.value;
91
112
  }
92
113
  return this.getFormatter(options).format(data);
93
114
  }
115
+ /**
116
+ * Formats the message into structured parts with the given placeholder data.
117
+ *
118
+ * For `NONE` format messages, returns a single text part with the raw value.
119
+ */
94
120
  formatToParts(data, options) {
95
121
  if (this.resolveFormat() === "NONE") {
96
122
  return [{ type: "text", value: this.value }];
97
123
  }
98
124
  return this.getFormatter(options).formatToParts(data);
99
125
  }
126
+ /**
127
+ * Returns a plain data object for this message.
128
+ *
129
+ * @param stripNotes - When true, notes are omitted from the result.
130
+ */
100
131
  getData(stripNotes = false) {
101
132
  return {
102
133
  key: this.key,
@@ -105,9 +136,17 @@ var MsgMessage = class _MsgMessage {
105
136
  notes: !stripNotes && this.notes.length > 0 ? this.notes : void 0
106
137
  };
107
138
  }
139
+ /**
140
+ * Returns the message value as a string.
141
+ */
108
142
  toString() {
109
143
  return this.value;
110
144
  }
145
+ /**
146
+ * Serializes this message to a formatted JSON string.
147
+ *
148
+ * @param stripNotes - When true, notes are omitted from the serialized data.
149
+ */
111
150
  toJSON(stripNotes = false) {
112
151
  return JSON.stringify(this.getData(stripNotes), null, 2);
113
152
  }
@@ -119,6 +158,12 @@ var MsgResource = class _MsgResource extends Map {
119
158
  _notes = [];
120
159
  _title;
121
160
  _project;
161
+ /**
162
+ * Builds a resource from {@link MsgResourceData} and an owning project.
163
+ *
164
+ * When `messages` is provided, each entry is added to the resource.
165
+ * When omitted, the resource starts empty.
166
+ */
122
167
  static create(data, project) {
123
168
  const { title, attributes, notes, messages } = data;
124
169
  const res = new _MsgResource(title, attributes, project, notes);
@@ -132,6 +177,9 @@ var MsgResource = class _MsgResource extends Map {
132
177
  }
133
178
  return res;
134
179
  }
180
+ /**
181
+ * Creates a resource bound to a project. Prefer {@link MsgResource.create}.
182
+ */
135
183
  constructor(title, attributes, project, notes) {
136
184
  super();
137
185
  this._title = title;
@@ -141,14 +189,23 @@ var MsgResource = class _MsgResource extends Map {
141
189
  notes.forEach((note) => this.addNote(note));
142
190
  }
143
191
  }
192
+ /**
193
+ * Returns true when the message's attributes match this resource's attributes.
194
+ */
144
195
  hasMatchingAttributes(message) {
145
196
  const res = this.attributes;
146
197
  const msg = message.attributes;
147
198
  return res.lang === msg.lang && res.dir === msg.dir && res.dnt === msg.dnt && this.resolveFormat(res) === this.resolveFormat(msg);
148
199
  }
200
+ /**
201
+ * Resolves a format from attributes, falling back to the library default.
202
+ */
149
203
  resolveFormat(attributes) {
150
204
  return attributes.format ?? MSG_DEFAULT_FORMAT;
151
205
  }
206
+ /**
207
+ * Pseudo-localizes an MF2 message by localizing only literal text parts.
208
+ */
152
209
  pseudoLocalizeMF2(source, options) {
153
210
  const msg = (0, import_messageformat2.parseMessage)(source);
154
211
  (0, import_messageformat2.visit)(msg, {
@@ -163,30 +220,47 @@ var MsgResource = class _MsgResource extends Map {
163
220
  });
164
221
  return (0, import_messageformat2.stringifyMessage)(msg);
165
222
  }
223
+ /** Locale and formatting metadata for this resource. */
166
224
  get attributes() {
167
225
  return this._attributes;
168
226
  }
227
+ /** Replaces the resource's locale and formatting metadata. */
169
228
  set attributes(attributes) {
170
229
  this._attributes = attributes;
171
230
  }
231
+ /** Notes attached to this resource for translators and tooling. */
172
232
  get notes() {
173
233
  return this._notes;
174
234
  }
235
+ /** Replaces the notes attached to this resource. */
175
236
  set notes(notes) {
176
237
  this._notes = notes;
177
238
  }
239
+ /**
240
+ * Appends a note to this resource.
241
+ */
178
242
  addNote(note) {
179
243
  this.notes.push(note);
180
244
  }
245
+ /** Title that identifies this resource within a project. */
181
246
  get title() {
182
247
  return this._title;
183
248
  }
249
+ /** Sets the title that identifies this resource within a project. */
184
250
  set title(title) {
185
251
  this._title = title;
186
252
  }
253
+ /**
254
+ * Returns the project this resource belongs to.
255
+ */
187
256
  getProject() {
188
257
  return this._project;
189
258
  }
259
+ /**
260
+ * Adds a message to this resource, merging resource attributes with any overrides.
261
+ *
262
+ * @returns This resource, for chaining.
263
+ */
190
264
  add(key, value, attributes, notes) {
191
265
  const merged = { ...this.attributes, ...attributes };
192
266
  const msg = MsgMessage.create({
@@ -198,6 +272,14 @@ var MsgResource = class _MsgResource extends Map {
198
272
  this.set(key, msg);
199
273
  return this;
200
274
  }
275
+ /**
276
+ * Builds a translated copy of this resource from translation data.
277
+ *
278
+ * Messages present in the translation replace the source; missing keys keep
279
+ * the source message. Notes are carried over from the source.
280
+ *
281
+ * @throws {TypeError} When the translation title does not match this resource.
282
+ */
201
283
  translate(data) {
202
284
  const { title, attributes, messages } = data;
203
285
  if (title !== this.title) {
@@ -235,7 +317,18 @@ var MsgResource = class _MsgResource extends Map {
235
317
  }
236
318
  return { ...attributes, format };
237
319
  }
320
+ /**
321
+ * Loads and applies translations for a locale via the project loader.
322
+ *
323
+ * When `lang` is the project's pseudo-locale, returns a pseudo-localized
324
+ * copy without calling the loader.
325
+ *
326
+ * @throws {Error} When the locale is unsupported or its language chain is empty.
327
+ */
238
328
  async getTranslation(lang) {
329
+ if (!lang) {
330
+ return _MsgResource.create(this.getData(), this.getProject());
331
+ }
239
332
  const project = this._project;
240
333
  const pseudoLocale = project.locales.pseudoLocale;
241
334
  if (lang === pseudoLocale) {
@@ -270,6 +363,14 @@ var MsgResource = class _MsgResource extends Map {
270
363
  }
271
364
  return translated;
272
365
  }
366
+ /**
367
+ * Returns a plain data object for this resource and its messages.
368
+ *
369
+ * Attributes that match the resource or project defaults are omitted where
370
+ * possible to keep the output compact.
371
+ *
372
+ * @param stripNotes - When true, notes are omitted from the result.
373
+ */
273
374
  getData(stripNotes = false) {
274
375
  const resourceFormat = this.resolveFormat(this.attributes);
275
376
  const projectFormat = this._project.format;
@@ -302,6 +403,11 @@ var MsgResource = class _MsgResource extends Map {
302
403
  messages
303
404
  };
304
405
  }
406
+ /**
407
+ * Serializes this resource to a formatted JSON string.
408
+ *
409
+ * @param stripNotes - When true, notes are omitted from the serialized data.
410
+ */
305
411
  toJSON(stripNotes = false) {
306
412
  return JSON.stringify(this.getData(stripNotes), null, 2);
307
413
  }
@@ -2,31 +2,87 @@ import { MsgAttributes, MsgNote, MsgInterface, MsgFormat } from '../MsgInterface
2
2
  import { MsgMessageData, MsgMessage } from '../MsgMessage/MsgMessage.cjs';
3
3
  import 'messageformat';
4
4
 
5
+ /**
6
+ * Plain data used to create or describe a {@link MsgResource}.
7
+ */
5
8
  type MsgResourceData = {
9
+ /** Title that identifies this resource within a project. */
6
10
  title: string;
11
+ /** Locale and formatting metadata for the resource. */
7
12
  attributes: MsgAttributes;
13
+ /** Optional notes for translators and tooling. */
8
14
  notes?: MsgNote[];
15
+ /** Optional list of messages in this resource. */
9
16
  messages?: MsgMessageData[];
10
17
  };
18
+ /**
19
+ * A named collection of messages belonging to a {@link MsgProject}.
20
+ *
21
+ * Resources inherit format defaults from their project, support translation
22
+ * loading (including pseudo-localization), and can serialize to plain data.
23
+ */
11
24
  declare class MsgResource extends Map<string, MsgMessage> implements MsgInterface {
12
25
  private _attributes;
13
26
  private _notes;
14
27
  private _title;
15
28
  private _project;
29
+ /**
30
+ * Builds a resource from {@link MsgResourceData} and an owning project.
31
+ *
32
+ * When `messages` is provided, each entry is added to the resource.
33
+ * When omitted, the resource starts empty.
34
+ */
16
35
  static create(data: MsgResourceData, project: MsgProject): MsgResource;
36
+ /**
37
+ * Creates a resource bound to a project. Prefer {@link MsgResource.create}.
38
+ */
17
39
  private constructor();
40
+ /**
41
+ * Returns true when the message's attributes match this resource's attributes.
42
+ */
18
43
  private hasMatchingAttributes;
44
+ /**
45
+ * Resolves a format from attributes, falling back to the library default.
46
+ */
19
47
  private resolveFormat;
48
+ /**
49
+ * Pseudo-localizes an MF2 message by localizing only literal text parts.
50
+ */
20
51
  private pseudoLocalizeMF2;
52
+ /** Locale and formatting metadata for this resource. */
21
53
  get attributes(): MsgAttributes;
54
+ /** Replaces the resource's locale and formatting metadata. */
22
55
  set attributes(attributes: MsgAttributes);
56
+ /** Notes attached to this resource for translators and tooling. */
23
57
  get notes(): MsgNote[];
58
+ /** Replaces the notes attached to this resource. */
24
59
  set notes(notes: MsgNote[]);
60
+ /**
61
+ * Appends a note to this resource.
62
+ */
25
63
  addNote(note: MsgNote): void;
64
+ /** Title that identifies this resource within a project. */
26
65
  get title(): string;
66
+ /** Sets the title that identifies this resource within a project. */
27
67
  set title(title: string);
68
+ /**
69
+ * Returns the project this resource belongs to.
70
+ */
28
71
  getProject(): MsgProject;
72
+ /**
73
+ * Adds a message to this resource, merging resource attributes with any overrides.
74
+ *
75
+ * @returns This resource, for chaining.
76
+ */
29
77
  add(key: string, value: string, attributes?: MsgAttributes, notes?: MsgNote[]): this;
78
+ /**
79
+ * Builds a translated copy of this resource from translation data.
80
+ *
81
+ * Messages present in the translation replace the source; missing keys keep
82
+ * the source message. Notes are carried over from the source.
83
+ *
84
+ * @throws {TypeError} When the translation title does not match this resource.
85
+ */
30
86
  translate(data: MsgResourceData): MsgResource;
31
87
  /**
32
88
  * Merge a `format` into an attribute set unless one is already present,
@@ -35,45 +91,111 @@ declare class MsgResource extends Map<string, MsgMessage> implements MsgInterfac
35
91
  * no format to preserve.
36
92
  */
37
93
  private preserveFormat;
38
- getTranslation(lang: string): Promise<MsgResource>;
94
+ /**
95
+ * Loads and applies translations for a locale via the project loader.
96
+ *
97
+ * When `lang` is the project's pseudo-locale, returns a pseudo-localized
98
+ * copy without calling the loader.
99
+ *
100
+ * @throws {Error} When the locale is unsupported or its language chain is empty.
101
+ */
102
+ getTranslation(lang?: string): Promise<MsgResource>;
103
+ /**
104
+ * Returns a plain data object for this resource and its messages.
105
+ *
106
+ * Attributes that match the resource or project defaults are omitted where
107
+ * possible to keep the output compact.
108
+ *
109
+ * @param stripNotes - When true, notes are omitted from the result.
110
+ */
39
111
  getData(stripNotes?: boolean): MsgResourceData;
112
+ /**
113
+ * Serializes this resource to a formatted JSON string.
114
+ *
115
+ * @param stripNotes - When true, notes are omitted from the serialized data.
116
+ */
40
117
  toJSON(stripNotes?: boolean): string;
41
118
  }
42
119
 
120
+ /**
121
+ * Project-level settings such as name, version, and default message format.
122
+ */
43
123
  type MsgProjectSettings = {
124
+ /** Display name of the localization project. */
44
125
  name: string;
126
+ /** Optional project version number. */
45
127
  version?: number;
128
+ /** Default message format inherited by resources and messages. */
46
129
  format?: MsgFormat;
47
130
  };
131
+ /**
132
+ * Map of a requested locale to the chain of locales used to load translations.
133
+ */
48
134
  type MsgTargetLocalesSettings = {
49
135
  [key: string]: string[];
50
136
  };
137
+ /**
138
+ * Locale configuration for a project: source, pseudo, and target locales.
139
+ */
51
140
  type MsgLocalesSettings = {
141
+ /** Locale of the source (authoring) strings. */
52
142
  sourceLocale: string;
143
+ /** Locale used for pseudo-localization during development. */
53
144
  pseudoLocale: string;
145
+ /** Target locales and their fallback load chains. */
54
146
  targetLocales: MsgTargetLocalesSettings;
55
147
  };
148
+ /**
149
+ * Async function that loads translated resource data for a project, title, and language.
150
+ */
56
151
  type MsgTranslationLoader = (project: string, title: string, lang: string) => Promise<MsgResourceData>;
152
+ /**
153
+ * Plain data used to create a {@link MsgProject}.
154
+ */
57
155
  type MsgProjectData = {
156
+ /** Project name, version, and default format. */
58
157
  project: MsgProjectSettings;
158
+ /** Source, pseudo, and target locale settings. */
59
159
  locales: MsgLocalesSettings;
160
+ /** Function used to load translations for a locale. */
60
161
  loader: MsgTranslationLoader;
61
162
  };
163
+ /**
164
+ * A localization project that holds settings, locales, and a translation loader.
165
+ *
166
+ * Resources are created against a project so they can inherit format defaults
167
+ * and load translations through the project's loader.
168
+ */
62
169
  declare class MsgProject {
170
+ /** Project name, version, and default format. */
63
171
  _project: MsgProjectSettings;
172
+ /** Source, pseudo, and target locale settings. */
64
173
  _locales: MsgLocalesSettings;
174
+ /** Function used to load translations for a locale. */
65
175
  _loader: MsgTranslationLoader;
176
+ /**
177
+ * Builds a project from {@link MsgProjectData}.
178
+ */
66
179
  static create(data: MsgProjectData): MsgProject;
180
+ /**
181
+ * Creates a project from its settings and loader. Prefer {@link MsgProject.create}.
182
+ */
67
183
  private constructor();
184
+ /** Project name, version, and default format. */
68
185
  get project(): MsgProjectSettings;
186
+ /** Source, pseudo, and target locale settings. */
69
187
  get locales(): MsgLocalesSettings;
188
+ /** Function used to load translations for a locale. */
70
189
  get loader(): MsgTranslationLoader;
71
190
  /**
72
191
  * The project-wide default message format. Resources (and, through them,
73
192
  * messages) inherit this value unless they specify their own.
74
193
  */
75
194
  get format(): MsgFormat;
195
+ /**
196
+ * Returns the translation load chain for a locale, or `undefined` if unsupported.
197
+ */
76
198
  getTargetLocale(locale: string): string[] | undefined;
77
199
  }
78
200
 
79
- export { MsgProject as M, MsgResource, type MsgResourceData, type MsgProjectData as a, type MsgTranslationLoader as b };
201
+ export { type MsgLocalesSettings as M, MsgResource, type MsgResourceData, MsgProject as a, type MsgProjectData as b, type MsgProjectSettings as c, type MsgTargetLocalesSettings as d, type MsgTranslationLoader as e };