@worldware/msg 0.9.0 → 0.10.1

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.
@@ -1,4 +1,210 @@
1
- export { DEFAULT_ATTRIBUTES, MSG_DEFAULT_FORMAT, MsgAttributes, MsgFormat, MsgInterface, MsgNote, NoteTypes } from './MsgInterface/MsgInterface.js';
2
- export { MsgMessage, MsgMessageData } from './MsgMessage/MsgMessage.js';
3
- export { M as MsgLocalesSettings, a as MsgProject, b as MsgProjectData, c as MsgProjectSettings, MsgResource, MsgResourceData, d as MsgTargetLocalesSettings, e as MsgTranslationLoader } from './MsgResource/MsgResource.js';
1
+ import { MsgAttributes, MsgNote, MsgInterface, NoteTypes, MsgFormat } from './MsgInterface/MsgInterface.js';
2
+ export { DEFAULT_ATTRIBUTES, MSG_DEFAULT_FORMAT } from './MsgInterface/MsgInterface.js';
3
+ import { MsgMessageData, MsgMessage } from './MsgMessage/MsgMessage.js';
4
4
  import 'messageformat';
5
+
6
+ /**
7
+ * Plain data used to create or describe a {@link MsgResource}.
8
+ */
9
+ type MsgResourceData = {
10
+ /** Title that identifies this resource within a project. */
11
+ title: string;
12
+ /** Locale and formatting metadata for the resource. */
13
+ attributes: MsgAttributes;
14
+ /** Optional notes for translators and tooling. */
15
+ notes?: MsgNote[];
16
+ /** Optional list of messages in this resource. */
17
+ messages?: MsgMessageData[];
18
+ };
19
+ /**
20
+ * A named collection of messages belonging to a {@link MsgProject}.
21
+ *
22
+ * Resources inherit format defaults from their project, support translation
23
+ * loading (including pseudo-localization), and can serialize to plain data.
24
+ */
25
+ declare class MsgResource extends Map<string, MsgMessage> implements MsgInterface {
26
+ private _attributes;
27
+ private _notes;
28
+ private _title;
29
+ private _project;
30
+ /**
31
+ * Builds a resource from {@link MsgResourceData} and an owning project.
32
+ *
33
+ * When `messages` is provided, each entry is added to the resource.
34
+ * When omitted, the resource starts empty.
35
+ */
36
+ static create(data: MsgResourceData, project: MsgProject): MsgResource;
37
+ /**
38
+ * Creates a resource bound to a project. Prefer {@link MsgResource.create}.
39
+ */
40
+ private constructor();
41
+ /**
42
+ * Returns true when the message's attributes match this resource's attributes.
43
+ */
44
+ private hasMatchingAttributes;
45
+ /**
46
+ * Resolves a format from attributes, falling back to the library default.
47
+ */
48
+ private resolveFormat;
49
+ /**
50
+ * Pseudo-localizes an MF2 message by localizing only literal text parts.
51
+ */
52
+ private pseudoLocalizeMF2;
53
+ /** Locale and formatting metadata for this resource. */
54
+ get attributes(): MsgAttributes;
55
+ /** Replaces the resource's locale and formatting metadata. */
56
+ set attributes(attributes: MsgAttributes);
57
+ /** Notes attached to this resource for translators and tooling. */
58
+ get notes(): MsgNote[];
59
+ /** Replaces the notes attached to this resource. */
60
+ set notes(notes: MsgNote[]);
61
+ /**
62
+ * Appends a note to this resource.
63
+ *
64
+ * @returns This resource, for chaining.
65
+ */
66
+ addNote(type: NoteTypes, content: string): this;
67
+ /**
68
+ * Appends a full note object to this resource.
69
+ *
70
+ * @returns This resource, for chaining.
71
+ */
72
+ private setNote;
73
+ /** Title that identifies this resource within a project. */
74
+ get title(): string;
75
+ /** Sets the title that identifies this resource within a project. */
76
+ set title(title: string);
77
+ /**
78
+ * Returns the project this resource belongs to.
79
+ */
80
+ getProject(): MsgProject;
81
+ /**
82
+ * Adds a message to this resource, merging resource attributes with any overrides.
83
+ *
84
+ * @returns This resource, for chaining.
85
+ */
86
+ add(key: string, value: string, attributes?: MsgAttributes, notes?: MsgNote[]): this;
87
+ /**
88
+ * Builds a translated copy of this resource from translation data.
89
+ *
90
+ * Messages present in the translation replace the source; missing keys keep
91
+ * the source message. Notes are carried over from the source.
92
+ *
93
+ * @throws {TypeError} When the translation title does not match this resource.
94
+ */
95
+ translate(data: MsgResourceData): MsgResource;
96
+ /**
97
+ * Merge a `format` into an attribute set unless one is already present,
98
+ * so translations inherit the source's format without overriding an
99
+ * explicitly translated one. Returns the input unchanged when there is
100
+ * no format to preserve.
101
+ */
102
+ private preserveFormat;
103
+ /**
104
+ * Loads and applies translations for a locale via the project loader.
105
+ *
106
+ * When `lang` is the project's pseudo-locale, returns a pseudo-localized
107
+ * copy without calling the loader.
108
+ *
109
+ * @throws {Error} When the locale is unsupported or its language chain is empty.
110
+ */
111
+ getTranslation(lang?: string): Promise<MsgResource>;
112
+ /**
113
+ * Returns a plain data object for this resource and its messages.
114
+ *
115
+ * Attributes that match the resource or project defaults are omitted where
116
+ * possible to keep the output compact.
117
+ *
118
+ * @param stripNotes - When true, notes are omitted from the result.
119
+ */
120
+ getData(stripNotes?: boolean): MsgResourceData;
121
+ /**
122
+ * Serializes this resource to a formatted JSON string.
123
+ *
124
+ * @param stripNotes - When true, notes are omitted from the serialized data.
125
+ */
126
+ toJSON(stripNotes?: boolean): string;
127
+ }
128
+
129
+ /**
130
+ * Project-level settings such as name, version, and default message format.
131
+ */
132
+ type MsgProjectSettings = {
133
+ /** Display name of the localization project. */
134
+ name: string;
135
+ /** Optional project version number. */
136
+ version?: number;
137
+ /** Default message format inherited by resources and messages. */
138
+ format?: MsgFormat;
139
+ };
140
+ /**
141
+ * Map of a requested locale to the chain of locales used to load translations.
142
+ */
143
+ type MsgTargetLocalesSettings = {
144
+ [key: string]: string[];
145
+ };
146
+ /**
147
+ * Locale configuration for a project: source, pseudo, and target locales.
148
+ */
149
+ type MsgLocalesSettings = {
150
+ /** Locale of the source (authoring) strings. */
151
+ sourceLocale: string;
152
+ /** Locale used for pseudo-localization during development. */
153
+ pseudoLocale: string;
154
+ /** Target locales and their fallback load chains. */
155
+ targetLocales: MsgTargetLocalesSettings;
156
+ };
157
+ /**
158
+ * Async function that loads translated resource data for a project, title, and language.
159
+ */
160
+ type MsgTranslationLoader = (project: string, title: string, lang: string) => Promise<MsgResourceData>;
161
+ /**
162
+ * Plain data used to create a {@link MsgProject}.
163
+ */
164
+ type MsgProjectData = {
165
+ /** Project name, version, and default format. */
166
+ project: MsgProjectSettings;
167
+ /** Source, pseudo, and target locale settings. */
168
+ locales: MsgLocalesSettings;
169
+ /** Function used to load translations for a locale. */
170
+ loader: MsgTranslationLoader;
171
+ };
172
+ /**
173
+ * A localization project that holds settings, locales, and a translation loader.
174
+ *
175
+ * Resources are created against a project so they can inherit format defaults
176
+ * and load translations through the project's loader.
177
+ */
178
+ declare class MsgProject {
179
+ /** Project name, version, and default format. */
180
+ _project: MsgProjectSettings;
181
+ /** Source, pseudo, and target locale settings. */
182
+ _locales: MsgLocalesSettings;
183
+ /** Function used to load translations for a locale. */
184
+ _loader: MsgTranslationLoader;
185
+ /**
186
+ * Builds a project from {@link MsgProjectData}.
187
+ */
188
+ static create(data: MsgProjectData): MsgProject;
189
+ /**
190
+ * Creates a project from its settings and loader. Prefer {@link MsgProject.create}.
191
+ */
192
+ private constructor();
193
+ /** Project name, version, and default format. */
194
+ get project(): MsgProjectSettings;
195
+ /** Source, pseudo, and target locale settings. */
196
+ get locales(): MsgLocalesSettings;
197
+ /** Function used to load translations for a locale. */
198
+ get loader(): MsgTranslationLoader;
199
+ /**
200
+ * The project-wide default message format. Resources (and, through them,
201
+ * messages) inherit this value unless they specify their own.
202
+ */
203
+ get format(): MsgFormat;
204
+ /**
205
+ * Returns the translation load chain for a locale, or `undefined` if unsupported.
206
+ */
207
+ getTargetLocale(locale: string): string[] | undefined;
208
+ }
209
+
210
+ export { MsgAttributes, MsgFormat, MsgInterface, type MsgLocalesSettings, MsgMessage, MsgMessageData, MsgNote, MsgProject, type MsgProjectData, type MsgProjectSettings, MsgResource, type MsgResourceData, type MsgTargetLocalesSettings, type MsgTranslationLoader, NoteTypes };
@@ -4,10 +4,10 @@ import {
4
4
  } from "../chunk-DJFPVXQ5.mjs";
5
5
  import {
6
6
  MsgResource
7
- } from "../chunk-IMOOTZIK.mjs";
7
+ } from "../chunk-HUWFAJAN.mjs";
8
8
  import {
9
9
  MsgMessage
10
- } from "../chunk-F3VAAZJZ.mjs";
10
+ } from "../chunk-OKEV7FY7.mjs";
11
11
  import {
12
12
  DEFAULT_ATTRIBUTES,
13
13
  MSG_DEFAULT_FORMAT
package/dist/index.cjs CHANGED
@@ -24,7 +24,9 @@ __export(index_exports, {
24
24
  MSG_DEFAULT_FORMAT: () => MSG_DEFAULT_FORMAT,
25
25
  MsgMessage: () => MsgMessage,
26
26
  MsgProject: () => MsgProject,
27
- MsgResource: () => MsgResource
27
+ MsgResource: () => MsgResource,
28
+ getLang: () => getLang,
29
+ setLang: () => setLang
28
30
  });
29
31
  module.exports = __toCommonJS(index_exports);
30
32
 
@@ -53,7 +55,7 @@ var MsgMessage = class _MsgMessage {
53
55
  this._value = value;
54
56
  this._attributes = attributes ? { ...DEFAULT_ATTRIBUTES, ...attributes } : {};
55
57
  if (notes) {
56
- notes.forEach((note) => this.addNote(note));
58
+ notes.forEach((note) => this.setNote(note));
57
59
  }
58
60
  }
59
61
  /**
@@ -82,9 +84,20 @@ var MsgMessage = class _MsgMessage {
82
84
  }
83
85
  /**
84
86
  * Appends a note to this message.
87
+ *
88
+ * @returns This message, for chaining.
89
+ */
90
+ addNote(type, content) {
91
+ return this.setNote({ type, content });
92
+ }
93
+ /**
94
+ * Appends a full note object to this message.
95
+ *
96
+ * @returns This message, for chaining.
85
97
  */
86
- addNote(note) {
98
+ setNote(note) {
87
99
  this.notes.push(note);
100
+ return this;
88
101
  }
89
102
  /**
90
103
  * The message's resolved format, defaulting to MF2 when not set or inherited.
@@ -188,7 +201,7 @@ var MsgResource = class _MsgResource extends Map {
188
201
  this._attributes = { ...DEFAULT_ATTRIBUTES, format: project.format, ...attributes };
189
202
  this._project = project;
190
203
  if (notes) {
191
- notes.forEach((note) => this.addNote(note));
204
+ notes.forEach((note) => this.setNote(note));
192
205
  }
193
206
  }
194
207
  /**
@@ -240,9 +253,20 @@ var MsgResource = class _MsgResource extends Map {
240
253
  }
241
254
  /**
242
255
  * Appends a note to this resource.
256
+ *
257
+ * @returns This resource, for chaining.
243
258
  */
244
- addNote(note) {
259
+ addNote(type, content) {
260
+ return this.setNote({ type, content });
261
+ }
262
+ /**
263
+ * Appends a full note object to this resource.
264
+ *
265
+ * @returns This resource, for chaining.
266
+ */
267
+ setNote(note) {
245
268
  this.notes.push(note);
269
+ return this;
246
270
  }
247
271
  /** Title that identifies this resource within a project. */
248
272
  get title() {
@@ -307,7 +331,7 @@ var MsgResource = class _MsgResource extends Map {
307
331
  });
308
332
  const notes = this.get(key)?.notes || [];
309
333
  notes.forEach((note) => {
310
- msg.addNote(note);
334
+ msg.addNote(note.type, note.content);
311
335
  });
312
336
  translated.set(key, msg);
313
337
  });
@@ -327,13 +351,13 @@ var MsgResource = class _MsgResource extends Map {
327
351
  *
328
352
  * @throws {Error} When the locale is unsupported or its language chain is empty.
329
353
  */
330
- async getTranslation(lang) {
331
- if (!lang) {
354
+ async getTranslation(lang2) {
355
+ if (!lang2) {
332
356
  return _MsgResource.create(this.getData(), this.getProject());
333
357
  }
334
358
  const project = this._project;
335
359
  const pseudoLocale = project.locales.pseudoLocale;
336
- if (lang === pseudoLocale) {
360
+ if (lang2 === pseudoLocale) {
337
361
  const pseudolocalizedData = {
338
362
  title: this.title,
339
363
  attributes: { ...this.attributes, lang: pseudoLocale },
@@ -349,18 +373,18 @@ var MsgResource = class _MsgResource extends Map {
349
373
  });
350
374
  return this.translate(pseudolocalizedData);
351
375
  }
352
- const languageChain = project.getTargetLocale(lang);
376
+ const languageChain = project.getTargetLocale(lang2);
353
377
  if (!languageChain) {
354
378
  throw new Error("Unsupported locale for resource.");
355
379
  }
356
380
  if (languageChain.length == 0) {
357
- throw new Error(`Empty language chain for locale: ${lang}`);
381
+ throw new Error(`Empty language chain for locale: ${lang2}`);
358
382
  }
359
383
  let translated = this;
360
384
  for (let i = 0; i < languageChain.length; i++) {
361
- const lang2 = languageChain[i];
362
- if (lang2 && project._locales.targetLocales[lang2]) {
363
- translated = await translated._project._loader(project.project.name, translated.title, lang2).then((data) => translated.translate(data));
385
+ const lang3 = languageChain[i];
386
+ if (lang3 && project._locales.targetLocales[lang3]) {
387
+ translated = await translated._project._loader(project.project.name, translated.title, lang3).then((data) => translated.translate(data));
364
388
  }
365
389
  }
366
390
  return translated;
@@ -476,11 +500,22 @@ var MsgProject = class _MsgProject {
476
500
  return this._locales.targetLocales[locale];
477
501
  }
478
502
  };
503
+
504
+ // src/lib/lang-utils.ts
505
+ var lang;
506
+ function setLang(tag) {
507
+ lang = tag;
508
+ }
509
+ function getLang() {
510
+ return lang;
511
+ }
479
512
  // Annotate the CommonJS export names for ESM import in node:
480
513
  0 && (module.exports = {
481
514
  DEFAULT_ATTRIBUTES,
482
515
  MSG_DEFAULT_FORMAT,
483
516
  MsgMessage,
484
517
  MsgProject,
485
- MsgResource
518
+ MsgResource,
519
+ getLang,
520
+ setLang
486
521
  });
package/dist/index.d.cts CHANGED
@@ -1,4 +1,5 @@
1
1
  export { DEFAULT_ATTRIBUTES, MSG_DEFAULT_FORMAT, MsgAttributes, MsgFormat, MsgInterface, MsgNote, NoteTypes } from './classes/MsgInterface/MsgInterface.cjs';
2
2
  export { MsgMessage, MsgMessageData } from './classes/MsgMessage/MsgMessage.cjs';
3
- export { M as MsgLocalesSettings, a as MsgProject, b as MsgProjectData, c as MsgProjectSettings, MsgResource, MsgResourceData, d as MsgTargetLocalesSettings, e as MsgTranslationLoader } from './classes/MsgResource/MsgResource.cjs';
3
+ export { MsgLocalesSettings, MsgProject, MsgProjectData, MsgProjectSettings, MsgResource, MsgResourceData, MsgTargetLocalesSettings, MsgTranslationLoader } from './classes/index.cjs';
4
+ export { getLang, setLang } from './lib/lang-utils.cjs';
4
5
  import 'messageformat';
package/dist/index.d.ts CHANGED
@@ -1,4 +1,5 @@
1
1
  export { DEFAULT_ATTRIBUTES, MSG_DEFAULT_FORMAT, MsgAttributes, MsgFormat, MsgInterface, MsgNote, NoteTypes } from './classes/MsgInterface/MsgInterface.js';
2
2
  export { MsgMessage, MsgMessageData } from './classes/MsgMessage/MsgMessage.js';
3
- export { M as MsgLocalesSettings, a as MsgProject, b as MsgProjectData, c as MsgProjectSettings, MsgResource, MsgResourceData, d as MsgTargetLocalesSettings, e as MsgTranslationLoader } from './classes/MsgResource/MsgResource.js';
3
+ export { MsgLocalesSettings, MsgProject, MsgProjectData, MsgProjectSettings, MsgResource, MsgResourceData, MsgTargetLocalesSettings, MsgTranslationLoader } from './classes/index.js';
4
+ export { getLang, setLang } from './lib/lang-utils.js';
4
5
  import 'messageformat';
package/dist/index.mjs CHANGED
@@ -1,13 +1,18 @@
1
1
  import "./chunk-ORHP7HGX.mjs";
2
+ import "./chunk-KQTWUIAM.mjs";
3
+ import {
4
+ getLang,
5
+ setLang
6
+ } from "./chunk-PU7ZZ5XH.mjs";
2
7
  import {
3
8
  MsgProject
4
9
  } from "./chunk-DJFPVXQ5.mjs";
5
10
  import {
6
11
  MsgResource
7
- } from "./chunk-IMOOTZIK.mjs";
12
+ } from "./chunk-HUWFAJAN.mjs";
8
13
  import {
9
14
  MsgMessage
10
- } from "./chunk-F3VAAZJZ.mjs";
15
+ } from "./chunk-OKEV7FY7.mjs";
11
16
  import {
12
17
  DEFAULT_ATTRIBUTES,
13
18
  MSG_DEFAULT_FORMAT
@@ -17,5 +22,7 @@ export {
17
22
  MSG_DEFAULT_FORMAT,
18
23
  MsgMessage,
19
24
  MsgProject,
20
- MsgResource
25
+ MsgResource,
26
+ getLang,
27
+ setLang
21
28
  };
@@ -1,3 +1,4 @@
1
+ import "../chunk-KQTWUIAM.mjs";
1
2
  import {
2
3
  getLang,
3
4
  setLang
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@worldware/msg",
3
- "version": "0.9.0",
3
+ "version": "0.10.1",
4
4
  "description": "Message localization tooling",
5
5
  "license": "MIT",
6
6
  "author": "Joel Sahleen",
@@ -22,7 +22,7 @@
22
22
  "default": "./dist/index.mjs"
23
23
  },
24
24
  "require": {
25
- "types": "./dist/index.d.cts",
25
+ "types": "./dist/index.d.ts",
26
26
  "default": "./dist/index.cjs"
27
27
  }
28
28
  }