@worldware/msg 0.7.0 → 0.7.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 +39 -14
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -50,15 +50,30 @@ An individual message with:
|
|
|
50
50
|
|
|
51
51
|
### Basic Setup
|
|
52
52
|
|
|
53
|
+
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:
|
|
54
|
+
|
|
53
55
|
```typescript
|
|
54
|
-
import { MsgProject
|
|
56
|
+
import { MsgProject } from '@worldware/msg';
|
|
57
|
+
|
|
58
|
+
const TRANSLATION_IMPORT_PATH = '../l10n/translations';
|
|
59
|
+
const loader = async (project, title, language) => {
|
|
60
|
+
const path = `${TRANSLATION_IMPORT_PATH}/${project}/${language}/${title}.json`;
|
|
61
|
+
try {
|
|
62
|
+
const module = await import(path, { with: { type: 'json' } });
|
|
63
|
+
return module.default;
|
|
64
|
+
} catch (error) {
|
|
65
|
+
console.warn(`Translations for locale ${language} could not be loaded.`, error);
|
|
66
|
+
return {
|
|
67
|
+
title,
|
|
68
|
+
attributes: { lang: language, dir: '' },
|
|
69
|
+
notes: [],
|
|
70
|
+
messages: []
|
|
71
|
+
};
|
|
72
|
+
}
|
|
73
|
+
};
|
|
55
74
|
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
project: {
|
|
59
|
-
name: 'my-app',
|
|
60
|
-
version: 1
|
|
61
|
-
},
|
|
75
|
+
export default MsgProject.create({
|
|
76
|
+
project: { name: 'my-app', version: 1 },
|
|
62
77
|
locales: {
|
|
63
78
|
sourceLocale: 'en',
|
|
64
79
|
pseudoLocale: 'en-XA',
|
|
@@ -66,18 +81,15 @@ const project = MsgProject.create({
|
|
|
66
81
|
'en': ['en'],
|
|
67
82
|
'es': ['es'],
|
|
68
83
|
'fr': ['fr'],
|
|
69
|
-
'fr-CA': ['fr', 'fr-CA']
|
|
84
|
+
'fr-CA': ['fr', 'fr-CA']
|
|
70
85
|
}
|
|
71
86
|
},
|
|
72
|
-
loader
|
|
73
|
-
// Custom loader to fetch translation data
|
|
74
|
-
const path = `./translations/${project}/${lang}/${title}.json`;
|
|
75
|
-
const data = await import(path);
|
|
76
|
-
return data;
|
|
77
|
-
}
|
|
87
|
+
loader
|
|
78
88
|
});
|
|
79
89
|
```
|
|
80
90
|
|
|
91
|
+
When using this in your app, import the default export as your project and pass it to `MsgResource.create` (see below).
|
|
92
|
+
|
|
81
93
|
### Creating a Resource
|
|
82
94
|
|
|
83
95
|
```typescript
|
|
@@ -126,6 +138,19 @@ const spanishResource = await resource.getTranslation('es');
|
|
|
126
138
|
// falling back to the source messages for missing translations
|
|
127
139
|
```
|
|
128
140
|
|
|
141
|
+
### Language fallbacks and translation layering
|
|
142
|
+
|
|
143
|
+
The project's `targetLocales` maps each requested locale to a **fallback chain**: an array of locale codes ordered from least specific to most specific (e.g. base language first, then region-specific). For example, `'zh-HK': ['zh', 'zh-Hant', 'zh-HK']` means that when you request `zh-HK`, the chain is first `zh`, then `zh-Hant`, then `zh-HK`. You can get the chain for any locale with `project.getTargetLocale(locale)`.
|
|
144
|
+
|
|
145
|
+
When you call `resource.getTranslation(locale)`:
|
|
146
|
+
|
|
147
|
+
1. The **source resource** (the resource you called it on) is the base.
|
|
148
|
+
2. For each locale in that locale's chain, the project **loader** is called to load that locale's translation data.
|
|
149
|
+
3. Each loaded dataset is **layered** onto the current result: messages in the new data add or override by key; keys missing in the new layer keep the value from the previous layer.
|
|
150
|
+
4. The final resource is the result after all layers have been applied.
|
|
151
|
+
|
|
152
|
+
So for `getTranslation('zh-HK')` with chain `['zh', 'zh-Hant', 'zh-HK']`, you get: source → then zh overlay → then zh-Hant overlay → then zh-HK overlay. Later entries in the chain override earlier ones for the same key; missing keys fall back to the previous layer (and ultimately to the source).
|
|
153
|
+
|
|
129
154
|
### Pseudo Localization
|
|
130
155
|
|
|
131
156
|
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:
|