@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.
- package/README.md +78 -54
- 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
|
|
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
|
-
```
|
|
57
|
+
```javascript
|
|
58
58
|
import { MsgProject } from '@worldware/msg';
|
|
59
59
|
|
|
60
|
-
const TRANSLATION_IMPORT_PATH =
|
|
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:
|
|
78
|
+
project: { name: "Main", version: 1, format: "MF1" },
|
|
79
79
|
locales: {
|
|
80
|
-
sourceLocale:
|
|
81
|
-
pseudoLocale:
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
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
|
-
```
|
|
127
|
-
//
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
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
|
-
```
|
|
172
|
-
// Load a translation for a
|
|
173
|
-
const
|
|
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
|
|
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
|
-
```
|
|
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: "
|
|
201
|
-
// Variables and
|
|
202
|
-
const greeting = pseudoResource.get('
|
|
203
|
-
// Result: "
|
|
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
|
-
```
|
|
209
|
-
// Add notes to messages
|
|
210
|
-
resource.add('complex-message', 'You have {
|
|
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.
|
|
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.
|
|
25
|
+
"types": "./dist/index.d.ts",
|
|
26
26
|
"default": "./dist/index.cjs"
|
|
27
27
|
}
|
|
28
28
|
}
|