@worldware/msg 0.10.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.
Files changed (2) hide show
  1. package/README.md +78 -54
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -52,12 +52,12 @@ An individual message with:
52
52
 
53
53
  ### Basic Setup
54
54
 
55
- The following example matches the ES module output of the **msg-cli** `create project` command—a typical project file that loads translations from JSON under a translations directory:
55
+ The following example matches the ES module output of the **msg-cli** command `msg create project Main en zh fr --format MF1`—a typical project file that loads translations from JSON under a translations directory (`TRANSLATION_IMPORT_PATH` may differ based on your `directories.i18n` / `directories.l10n` layout):
56
56
 
57
- ```typescript
57
+ ```javascript
58
58
  import { MsgProject } from '@worldware/msg';
59
59
 
60
- const TRANSLATION_IMPORT_PATH = '../l10n/translations';
60
+ const TRANSLATION_IMPORT_PATH = "../l10n/translations";
61
61
  const loader = async (project, title, language) => {
62
62
  const path = `${TRANSLATION_IMPORT_PATH}/${project}/${language}/${title}.json`;
63
63
  try {
@@ -75,59 +75,78 @@ const loader = async (project, title, language) => {
75
75
  };
76
76
 
77
77
  export default MsgProject.create({
78
- project: { name: 'my-app', version: 1 },
78
+ project: { name: "Main", version: 1, format: "MF1" },
79
79
  locales: {
80
- sourceLocale: 'en',
81
- pseudoLocale: 'en-XA',
82
- targetLocales: {
83
- 'en': ['en'],
84
- 'es': ['es'],
85
- 'fr': ['fr'],
86
- 'fr-CA': ['fr', 'fr-CA']
87
- }
80
+ sourceLocale: "en",
81
+ pseudoLocale: "en-XA",
82
+ targetLocales: {"en":["en"],"zh":["zh"],"fr":["fr"]}
88
83
  },
89
84
  loader
90
85
  });
91
86
  ```
92
87
 
93
- When using this in your app, import the default export as your project and pass it to `MsgResource.create` (see below).
88
+ When using this in your app, import the default export as your project (msg-cli scaffolds resources that import it via `#i18n/projects/Main.js`).
94
89
 
95
90
  ### Creating a Resource
96
91
 
97
- ```typescript
98
- // Create a resource with messages
99
- const resource = MsgResource.create({
100
- title: 'CommonMessages',
101
- attributes: {
102
- lang: 'en',
103
- dir: 'ltr'
104
- },
105
- messages: [
106
- {
107
- key: 'greeting',
108
- value: 'Hello, {$name}!'
109
- },
110
- {
111
- key: 'welcome',
112
- value: 'Welcome to our application'
113
- }
114
- ]
115
- }, project);
92
+ The following example matches the ES module output of **msg-cli** `msg create resource Main Messages`:
116
93
 
117
- // Or add messages programmatically
118
- resource.add('goodbye', 'Goodbye, {$name}!', {
119
- lang: 'en',
120
- dir: 'ltr'
121
- });
94
+ ```javascript
95
+ /** ESM module **/
96
+
97
+ import { MsgResource, getLang } from '@worldware/msg';
98
+ import project from '#i18n/projects/Main.js';
99
+
100
+ /** Create a MsgResource object */
101
+
102
+ export const resource = MsgResource.create({
103
+ title: 'Messages',
104
+ attributes: {
105
+ lang: 'en',
106
+ dir: 'ltr'
107
+ },
108
+ notes: [
109
+ {type: 'DESCRIPTION', content: 'This is the Messages resource.'}
110
+ ]
111
+ }, project);
112
+
113
+ /**
114
+ * Add messages to the resource using add(key, value, attributes, notes)
115
+ * The add method is chainable.
116
+ */
117
+
118
+ resource
119
+ .add('sampleKey', 'Sample value.', {}, [
120
+ { type: 'DESCRIPTION', content: 'This is first message.' }
121
+ ])
122
+ .add('sampleKey2', 'Hi, {name}', { dnt: true }, [
123
+ { type: 'DESCRIPTION', content: 'This is the second message.' },
124
+ { type: 'PARAMETERS', content: 'The {name} parameter holds the user name.' }
125
+ ]);
126
+
127
+ /**
128
+ * An async function to get a translated version of the resource
129
+ * If the runtime language has not been set using `setLang()`,
130
+ * it will return the original resource
131
+ */
132
+ export async function getMessages() {
133
+ return await resource.getTranslation(getLang());
134
+ }
122
135
  ```
123
136
 
124
137
  ### Formatting Messages
125
138
 
126
- ```typescript
127
- // Get a message and format it
128
- const greetingMsg = resource.get('greeting');
129
- const formatted = greetingMsg?.format({ name: 'Alice' });
130
- // Result: "Hello, Alice!"
139
+ ```javascript
140
+ // Messages inherit MF1 from the Main project scaffold above
141
+ resource.get('sampleKey')?.format();
142
+ // Result: "Sample value."
143
+
144
+ resource.get('sampleKey2')?.format({ name: 'Alice' });
145
+ // Result: "Hi, Alice"
146
+
147
+ // Prefer getMessages() when you want the runtime locale (via setLang/getLang)
148
+ const messages = await getMessages();
149
+ messages.get('sampleKey2')?.format({ name: 'Alice' });
131
150
  ```
132
151
 
133
152
  ### Message Formats (MF1, MF2, NONE)
@@ -140,6 +159,8 @@ Every message is formatted according to its resolved `format` attribute:
140
159
 
141
160
  The `format` is inheritable: a resource inherits its project's `format` unless it sets its own, and a message inherits its resource's `format` unless it sets its own. The default is `MF2`, so existing code keeps working unchanged. Use a TypeScript union (`'MF1' | 'MF2' | 'NONE'`) — there is no enum.
142
161
 
162
+ The following is a **separate illustration** of format inheritance and per-message overrides (not the CLI `Main` / `Messages` scaffold above):
163
+
143
164
  ```typescript
144
165
  import { MsgProject, MsgResource } from '@worldware/msg';
145
166
 
@@ -168,12 +189,15 @@ When serializing, an inherited `format` is omitted to keep output compact: a res
168
189
 
169
190
  ### Loading Translations
170
191
 
171
- ```typescript
172
- // Load a translation for a specific language
173
- const spanishResource = await resource.getTranslation('es');
192
+ ```javascript
193
+ // Load a translation for a configured target locale (zh or fr in the Main project)
194
+ const zhResource = await resource.getTranslation('zh');
174
195
 
175
- // The translated resource will have Spanish messages where available,
196
+ // The translated resource will have Chinese messages where available,
176
197
  // falling back to the source messages for missing translations
198
+
199
+ // Or use the scaffolded helper (honors setLang() / getLang())
200
+ const messages = await getMessages();
177
201
  ```
178
202
 
179
203
  ### Language fallbacks and translation layering
@@ -193,21 +217,21 @@ So for `getTranslation('zh-HK')` with chain `['zh', 'zh-Hant', 'zh-HK']`, you ge
193
217
 
194
218
  When `getTranslation` is called with the project's `pseudoLocale` (e.g. `en-XA`), it returns a new resource with pseudolocalized message values—useful for testing UI layout and finding hardcoded strings without loading translation files:
195
219
 
196
- ```typescript
220
+ ```javascript
197
221
  // Request pseudolocalized messages (project locales.pseudoLocale is 'en-XA')
198
222
  const pseudoResource = await resource.getTranslation('en-XA');
199
223
 
200
- // Message values are transformed: "Hello, {$name}!" → "Ħḗḗŀŀǿǿ, {$name}!"
201
- // Variables and MF2 syntax are preserved; only literal text is pseudolocalized
202
- const greeting = pseudoResource.get('greeting')?.format({ name: 'Alice' });
203
- // Result: "Ħḗḗŀŀǿǿ, Alice!"
224
+ // Message values are transformed: "Hi, {name}" → "Ħī, {name}"
225
+ // Variables and message-format syntax are preserved; only literal text is pseudolocalized
226
+ const greeting = pseudoResource.get('sampleKey2')?.format({ name: 'Alice' });
227
+ // Result: "Ħī, Alice"
204
228
  ```
205
229
 
206
230
  ### Working with Attributes and Notes
207
231
 
208
- ```typescript
209
- // Add notes to messages
210
- resource.add('complex-message', 'You have {$count} items', {
232
+ ```javascript
233
+ // Add notes to messages (MF1 syntax, matching the Main project's format)
234
+ resource.add('complex-message', 'You have {count} items', {
211
235
  lang: 'en',
212
236
  dir: 'ltr',
213
237
  dnt: false // do-not-translate flag
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@worldware/msg",
3
- "version": "0.10.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
  }