@worldware/msg 0.6.4 → 0.7.1

package/README.md

@@ -8,6 +8,7 @@ A TypeScript library for managing internationalization (i18n) messages with supp
 
 - **Message Management**: Organize messages into resources with keys and values
 - **Translation Loading**: Load translations from external sources via customizable loaders
+- **Pseudo Localization**: Request a pseudolocalized resource for UI testing via `getTranslation(pseudoLocale)`
 - **Message Formatting**: Format messages with parameters using MessageFormat 2 (MF2) syntax
 - **Attributes & Notes**: Attach metadata (language, direction, do-not-translate flags) and notes to messages
 - **Project Configuration**: Configure projects with locale settings and translation loaders
@@ -25,6 +26,7 @@ npm install @worldware/msg
 A project configuration that defines:
 - Project name and version
 - Source and target locales (with language fallback chains)
+- Pseudo locale (for pseudolocalized output via `getTranslation`)
 - A translation loader function
 
 ### MsgResource
@@ -48,15 +50,30 @@ An individual message with:
 
 ### Basic Setup
 
+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:
+
 ```typescript
-import { MsgProject, MsgResource } from '@worldware/msg';
+import { MsgProject } from '@worldware/msg';
+
+const TRANSLATION_IMPORT_PATH = '../l10n/translations';
+const loader = async (project, title, language) => {
+  const path = `${TRANSLATION_IMPORT_PATH}/${project}/${language}/${title}.json`;
+  try {
+    const module = await import(path, { with: { type: 'json' } });
+    return module.default;
+  } catch (error) {
+    console.warn(`Translations for locale ${language} could not be loaded.`, error);
+    return {
+      title,
+      attributes: { lang: language, dir: '' },
+      notes: [],
+      messages: []
+    };
+  }
+};
 
-// Create a project configuration
-const project = MsgProject.create({
-  project: {
-    name: 'my-app',
-    version: 1
-  },
+export default MsgProject.create({
+  project: { name: 'my-app', version: 1 },
   locales: {
     sourceLocale: 'en',
     pseudoLocale: 'en-XA',
@@ -64,18 +81,15 @@ const project = MsgProject.create({
       'en': ['en'],
       'es': ['es'],
       'fr': ['fr'],
-      'fr-CA': ['fr', 'fr-CA']  // Falls back to 'fr' if 'fr-CA' not available
+      'fr-CA': ['fr', 'fr-CA']
     }
   },
-  loader: async (project, title, lang) => {
-    // Custom loader to fetch translation data
-    const path = `./translations/${project}/${lang}/${title}.json`;
-    const data = await import(path);
-    return data;
-  }
+  loader
 });
 ```
 
+When using this in your app, import the default export as your project and pass it to `MsgResource.create` (see below).
+
 ### Creating a Resource
 
 ```typescript
@@ -89,7 +103,7 @@ const resource = MsgResource.create({
   messages: [
     {
       key: 'greeting',
-      value: 'Hello, {name}!'
+      value: 'Hello, {$name}!'
     },
     {
       key: 'welcome',
@@ -99,7 +113,7 @@ const resource = MsgResource.create({
 }, project);
 
 // Or add messages programmatically
-resource.add('goodbye', 'Goodbye, {name}!', {
+resource.add('goodbye', 'Goodbye, {$name}!', {
   lang: 'en',
   dir: 'ltr'
 });
@@ -124,11 +138,38 @@ const spanishResource = await resource.getTranslation('es');
 // falling back to the source messages for missing translations
 ```
 
+### Language fallbacks and translation layering
+
+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)`.
+
+When you call `resource.getTranslation(locale)`:
+
+1. The **source resource** (the resource you called it on) is the base.
+2. For each locale in that locale's chain, the project **loader** is called to load that locale's translation data.
+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.
+4. The final resource is the result after all layers have been applied.
+
+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).
+
+### Pseudo Localization
+
+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:
+
+```typescript
+// Request pseudolocalized messages (project locales.pseudoLocale is 'en-XA')
+const pseudoResource = await resource.getTranslation('en-XA');
+
+// Message values are transformed: "Hello, {$name}!" → "Ħḗḗŀŀǿǿ, {$name}!"
+// Variables and MF2 syntax are preserved; only literal text is pseudolocalized
+const greeting = pseudoResource.get('greeting')?.format({ name: 'Alice' });
+// Result: "Ħḗḗŀŀǿǿ, Alice!"
+```
+
 ### Working with Attributes and Notes
 
 ```typescript
 // Add notes to messages
-resource.add('complex-message', 'This is a complex message', {
+resource.add('complex-message', 'You have {$count} items', {
   lang: 'en',
   dir: 'ltr',
   dnt: false // do-not-translate flag
@@ -188,7 +229,7 @@ const data = resource.getData();
 **Methods:**
 - `add(key: string, value: string, attributes?: MsgAttributes, notes?: MsgNote[]): MsgResource` - Add a message
 - `translate(data: MsgResourceData): MsgResource` - Create a translated version
-- `getTranslation(lang: string): Promise<MsgResource>` - Load and apply translations
+- `getTranslation(lang: string): Promise<MsgResource>` - Load and apply translations. When `lang` matches the project's `pseudoLocale`, returns a resource with pseudolocalized message values instead of loading from the loader.
 - `getProject(): MsgProject` - Returns the project instance associated with the resource
 - `getData(stripNotes?: boolean): MsgResourceData` - Get resource data. Message objects in the output omit `attributes` when they match the resource's attributes (to avoid redundancy)
 - `toJSON(stripNotes?: boolean): string` - Serialize to JSON

package/dist/{chunk-AWSZFTAJ.mjs → chunk-2QUOYESW.mjs}

@@ -6,6 +6,8 @@ import {
 } from "./chunk-QWBDIKQK.mjs";
 
 // src/classes/MsgResource/MsgResource.ts
+import { parseMessage, stringifyMessage, visit } from "messageformat";
+import { localize } from "pseudo-localization";
 var MsgResource = class _MsgResource extends Map {
   _attributes = {};
   _notes = [];
@@ -38,6 +40,20 @@ var MsgResource = class _MsgResource extends Map {
     const msg = message.attributes;
     return res.lang === msg.lang && res.dir === msg.dir && res.dnt === msg.dnt;
   }
+  pseudoLocalizeMF2(source, options) {
+    const msg = parseMessage(source);
+    visit(msg, {
+      pattern: (pattern) => {
+        for (let i = 0; i < pattern.length; i++) {
+          const part = pattern[i];
+          if (typeof part === "string") {
+            pattern[i] = localize(part, options);
+          }
+        }
+      }
+    });
+    return stringifyMessage(msg);
+  }
   get attributes() {
     return this._attributes;
   }
@@ -104,6 +120,23 @@ var MsgResource = class _MsgResource extends Map {
   }
   async getTranslation(lang) {
     const project = this._project;
+    const pseudoLocale = project.locales.pseudoLocale;
+    if (lang === pseudoLocale) {
+      const pseudolocalizedData = {
+        title: this.title,
+        attributes: { ...this.attributes, lang: pseudoLocale },
+        notes: this.notes.length > 0 ? this.notes : void 0,
+        messages: []
+      };
+      this.forEach((msg) => {
+        pseudolocalizedData.messages.push({
+          key: msg.key,
+          value: this.pseudoLocalizeMF2(msg.value),
+          attributes: { ...this.attributes, lang: pseudoLocale }
+        });
+      });
+      return this.translate(pseudolocalizedData);
+    }
     const languageChain = project.getTargetLocale(lang);
     if (!languageChain) {
       throw new Error("Unsupported locale for resource.");

package/dist/classes/MsgProject/MsgProject.d.cts

@@ -46,6 +46,7 @@ declare class MsgResource extends Map<string, MsgMessage> implements MsgInterfac
     static create(data: MsgResourceData, project: MsgProject): MsgResource;
     private constructor();
     private hasMatchingAttributes;
+    private pseudoLocalizeMF2;
     get attributes(): MsgAttributes;
     set attributes(attributes: MsgAttributes);
     get notes(): MsgNote[];

package/dist/classes/MsgProject/MsgProject.d.ts

@@ -46,6 +46,7 @@ declare class MsgResource extends Map<string, MsgMessage> implements MsgInterfac
     static create(data: MsgResourceData, project: MsgProject): MsgResource;
     private constructor();
     private hasMatchingAttributes;
+    private pseudoLocalizeMF2;
     get attributes(): MsgAttributes;
     set attributes(attributes: MsgAttributes);
     get notes(): MsgNote[];

package/dist/classes/MsgResource/MsgResource.cjs

@@ -23,6 +23,8 @@ __export(MsgResource_exports, {
   MsgResource: () => MsgResource
 });
 module.exports = __toCommonJS(MsgResource_exports);
+var import_messageformat2 = require("messageformat");
+var import_pseudo_localization = require("pseudo-localization");
 
 // src/classes/MsgMessage/MsgMessage.ts
 var import_messageformat = require("messageformat");
@@ -130,6 +132,20 @@ var MsgResource = class _MsgResource extends Map {
     const msg = message.attributes;
     return res.lang === msg.lang && res.dir === msg.dir && res.dnt === msg.dnt;
   }
+  pseudoLocalizeMF2(source, options) {
+    const msg = (0, import_messageformat2.parseMessage)(source);
+    (0, import_messageformat2.visit)(msg, {
+      pattern: (pattern) => {
+        for (let i = 0; i < pattern.length; i++) {
+          const part = pattern[i];
+          if (typeof part === "string") {
+            pattern[i] = (0, import_pseudo_localization.localize)(part, options);
+          }
+        }
+      }
+    });
+    return (0, import_messageformat2.stringifyMessage)(msg);
+  }
   get attributes() {
     return this._attributes;
   }
@@ -196,6 +212,23 @@ var MsgResource = class _MsgResource extends Map {
   }
   async getTranslation(lang) {
     const project = this._project;
+    const pseudoLocale = project.locales.pseudoLocale;
+    if (lang === pseudoLocale) {
+      const pseudolocalizedData = {
+        title: this.title,
+        attributes: { ...this.attributes, lang: pseudoLocale },
+        notes: this.notes.length > 0 ? this.notes : void 0,
+        messages: []
+      };
+      this.forEach((msg) => {
+        pseudolocalizedData.messages.push({
+          key: msg.key,
+          value: this.pseudoLocalizeMF2(msg.value),
+          attributes: { ...this.attributes, lang: pseudoLocale }
+        });
+      });
+      return this.translate(pseudolocalizedData);
+    }
     const languageChain = project.getTargetLocale(lang);
     if (!languageChain) {
       throw new Error("Unsupported locale for resource.");

package/dist/classes/MsgResource/MsgResource.mjs

@@ -1,6 +1,6 @@
 import {
   MsgResource
-} from "../../chunk-AWSZFTAJ.mjs";
+} from "../../chunk-2QUOYESW.mjs";
 import "../../chunk-WUDKNZV2.mjs";
 import "../../chunk-QWBDIKQK.mjs";
 export {

package/dist/classes/index.cjs

@@ -100,6 +100,8 @@ var MsgMessage = class _MsgMessage {
 };
 
 // src/classes/MsgResource/MsgResource.ts
+var import_messageformat2 = require("messageformat");
+var import_pseudo_localization = require("pseudo-localization");
 var MsgResource = class _MsgResource extends Map {
   _attributes = {};
   _notes = [];
@@ -132,6 +134,20 @@ var MsgResource = class _MsgResource extends Map {
     const msg = message.attributes;
     return res.lang === msg.lang && res.dir === msg.dir && res.dnt === msg.dnt;
   }
+  pseudoLocalizeMF2(source, options) {
+    const msg = (0, import_messageformat2.parseMessage)(source);
+    (0, import_messageformat2.visit)(msg, {
+      pattern: (pattern) => {
+        for (let i = 0; i < pattern.length; i++) {
+          const part = pattern[i];
+          if (typeof part === "string") {
+            pattern[i] = (0, import_pseudo_localization.localize)(part, options);
+          }
+        }
+      }
+    });
+    return (0, import_messageformat2.stringifyMessage)(msg);
+  }
   get attributes() {
     return this._attributes;
   }
@@ -198,6 +214,23 @@ var MsgResource = class _MsgResource extends Map {
   }
   async getTranslation(lang) {
     const project = this._project;
+    const pseudoLocale = project.locales.pseudoLocale;
+    if (lang === pseudoLocale) {
+      const pseudolocalizedData = {
+        title: this.title,
+        attributes: { ...this.attributes, lang: pseudoLocale },
+        notes: this.notes.length > 0 ? this.notes : void 0,
+        messages: []
+      };
+      this.forEach((msg) => {
+        pseudolocalizedData.messages.push({
+          key: msg.key,
+          value: this.pseudoLocalizeMF2(msg.value),
+          attributes: { ...this.attributes, lang: pseudoLocale }
+        });
+      });
+      return this.translate(pseudolocalizedData);
+    }
     const languageChain = project.getTargetLocale(lang);
     if (!languageChain) {
       throw new Error("Unsupported locale for resource.");

package/dist/classes/index.mjs

@@ -4,7 +4,7 @@ import {
 } from "../chunk-XS43NAP2.mjs";
 import {
   MsgResource
-} from "../chunk-AWSZFTAJ.mjs";
+} from "../chunk-2QUOYESW.mjs";
 import {
   MsgMessage
 } from "../chunk-WUDKNZV2.mjs";

package/dist/index.cjs

@@ -100,6 +100,8 @@ var MsgMessage = class _MsgMessage {
 };
 
 // src/classes/MsgResource/MsgResource.ts
+var import_messageformat2 = require("messageformat");
+var import_pseudo_localization = require("pseudo-localization");
 var MsgResource = class _MsgResource extends Map {
   _attributes = {};
   _notes = [];
@@ -132,6 +134,20 @@ var MsgResource = class _MsgResource extends Map {
     const msg = message.attributes;
     return res.lang === msg.lang && res.dir === msg.dir && res.dnt === msg.dnt;
   }
+  pseudoLocalizeMF2(source, options) {
+    const msg = (0, import_messageformat2.parseMessage)(source);
+    (0, import_messageformat2.visit)(msg, {
+      pattern: (pattern) => {
+        for (let i = 0; i < pattern.length; i++) {
+          const part = pattern[i];
+          if (typeof part === "string") {
+            pattern[i] = (0, import_pseudo_localization.localize)(part, options);
+          }
+        }
+      }
+    });
+    return (0, import_messageformat2.stringifyMessage)(msg);
+  }
   get attributes() {
     return this._attributes;
   }
@@ -198,6 +214,23 @@ var MsgResource = class _MsgResource extends Map {
   }
   async getTranslation(lang) {
     const project = this._project;
+    const pseudoLocale = project.locales.pseudoLocale;
+    if (lang === pseudoLocale) {
+      const pseudolocalizedData = {
+        title: this.title,
+        attributes: { ...this.attributes, lang: pseudoLocale },
+        notes: this.notes.length > 0 ? this.notes : void 0,
+        messages: []
+      };
+      this.forEach((msg) => {
+        pseudolocalizedData.messages.push({
+          key: msg.key,
+          value: this.pseudoLocalizeMF2(msg.value),
+          attributes: { ...this.attributes, lang: pseudoLocale }
+        });
+      });
+      return this.translate(pseudolocalizedData);
+    }
     const languageChain = project.getTargetLocale(lang);
     if (!languageChain) {
       throw new Error("Unsupported locale for resource.");

package/dist/index.mjs

@@ -4,7 +4,7 @@ import {
 } from "./chunk-XS43NAP2.mjs";
 import {
   MsgResource
-} from "./chunk-AWSZFTAJ.mjs";
+} from "./chunk-2QUOYESW.mjs";
 import {
   MsgMessage
 } from "./chunk-WUDKNZV2.mjs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@worldware/msg",
-  "version": "0.6.4",
+  "version": "0.7.1",
   "description": "Message localization tooling",
   "license": "MIT",
   "author": "Joel Sahleen",
@@ -38,7 +38,8 @@
     "vitest": "^4.0.15"
   },
   "dependencies": {
-    "messageformat": "4.0.0-10"
+    "messageformat": "4.0.0-10",
+    "pseudo-localization": "^2.4.0"
   },
   "scripts": {
     "build": "tsup",