smartloc 2.0.9 → 2.0.11

package/AGENTS.md

@@ -0,0 +1,69 @@
+# smartloc: instructions for AI coding agents
+
+This file is for agents writing code that **uses** the `smartloc` package. It is shipped in the npm tarball, so it is readable from `node_modules/smartloc/AGENTS.md`. Detailed docs are in `node_modules/smartloc/docs/`.
+
+## What it is
+
+i18n via tagged template strings. `loc`...`` returns a `LocStr`: an immutable object that is translated lazily, when `.toString()`/`JSON.stringify` run inside a locale context, or when React renders it. Server (Express, Apollo GraphQL) and browser (React 19) are supported.
+
+## Entry points
+
+| Import | Exports |
+|---|---|
+| `smartloc` | `loc`, `setDefaultLocale`, `addLocale`, `changeLocale`, `removeLocale`, `clearLocales`, `getDefaultLocale`, `withLocales`, `singleLoc`, `multiLoc`, `joinArray`, `useAsString`, `isLocStr`, `loadJsonLocale`, `toJsonStorable`, `toLocalizable`, `jsonParseLocalized`, `translateObject`, `translateInContext`, `withSerializationContext`, types `LocStr`, `TranslationOf<T>`, `StorableOf<T>` |
+| `smartloc/express` | default export: middleware factory `(options?) => RequestHandler` |
+| `smartloc/graphql` | `GLocString`, `localizeSchema`, `localizedContext`, `localizedContextObject` |
+| `smartloc/node` | `loadAllLocales(dir, merge?)`, `loadLocale(file, merge?)` (Node only, uses fs) |
+
+## Rules
+
+1. **Never build translated strings by hand.** Return `loc('id')`text ${value}`` and let the boundary translate. Do not call `.toString()` in business code unless you need a string for a log or a non-smartloc API.
+2. **Always give an explicit ID** for anything a user sees: `loc('area.name')`...``. Auto IDs (``loc`...``) change when the text changes and lose translations. Use `.` to namespace IDs; the CLI groups files by the prefix before the first dot.
+3. **Call `setDefaultLocale('xx')` once at startup**, before any translation. Use a literal string: the CLI reads it from the source.
+4. **Placeholders**: strings, numbers, `Date`, other `LocStr`, React nodes. Numbers and dates are locale-formatted automatically, do not pre-format them. Do not concatenate `LocStr` with `+`; nest them as placeholders or use `joinArray`.
+5. **Plurals**: `loc.plural(count)('id')`${count} items``. Count 1 uses the `singular` form from translation files. The default language singular is only in the default-locale file, generated with `--defaultLocale`.
+6. **Express**: `app.use(smartloc())` before routes. `res.json()`, `res.jsonp()`, `res.send()` are then translated from `Accept-Language`. Pass `{ waitFor: promise }` when locales load asynchronously.
+7. **GraphQL**: field type `GLocString`, `schema = localizeSchema(schema)`, `context: localizedContext(fn)`. `JSON`/`JSONObject` scalar fields are translated recursively too.
+8. **React**: render a `LocStr` directly as a child (`<h1>{loc`...`}</h1>`). For string-only props (`placeholder`, `title`, `aria-*`) use `useAsString(locStr)` inside the component. Do not call `.toString()` during render: it does not re-render on `changeLocale()`.
+9. **Translation files**: run `npx smartloc collect --format=json --locales=fr,de --defaultLocale=en` (writes `./i18n/<locale>.json`). Do not edit `source` fields; fill `target`. Load with `loadAllLocales('./i18n')` (Node) or `loadJsonLocale(url | object)` (browser). Prefer this over hand-written `addLocale` calls.
+10. **Persisting `LocStr`** (DB, queues): `JSON.stringify(toJsonStorable(value))` to store, `toLocalizable(JSON.parse(text))` to restore. Plain `JSON.stringify` outside a serialization context translates to the default language and loses translatability. `transform()` and `joinArray()` results cannot be stored.
+11. **Cloning**: `LocStr` are frozen objects tagged with a symbol. In deep clones, skip values where `isLocStr(v)` is true.
+12. **Locale IDs**: `'fr'` or `'fr-FR'`, case-insensitive. `fr-FR` also serves requests for `fr` and `fr-CA` when no closer match exists.
+
+## Minimal examples
+
+```ts
+// server bootstrap
+import { setDefaultLocale } from 'smartloc';
+import { loadAllLocales } from 'smartloc/node';
+setDefaultLocale('en');
+await loadAllLocales('./i18n');
+```
+
+```ts
+// express
+import smartloc from 'smartloc/express';
+app.use(smartloc());
+app.get('/', (req, res) => res.json({ message: loc('home.hello')`Hello ${req.query.name}` }));
+```
+
+```tsx
+// react
+const hint = useAsString(loc('search.hint')`Type to search`);
+return <input placeholder={hint} aria-label={hint} />;
+```
+
+```ts
+// test / one-off translation
+withLocales(['fr'], () => msg.toString());
+translateObject('fr', { title: loc('t')`Hi` });
+```
+
+## Translation file shape (JSON)
+
+```json
+{ "sourceLanguage": "en", "targetLanguage": "fr",
+  "resources": { "home": { "hello": { "source": "Hello {0}", "target": "Bonjour {0}" } },
+                 "cart":  { "items": { "source": { "singular": null, "plural": "{0} items" },
+                                       "target": { "singular": "Un article", "plural": "{0} articles" } } } } }
+```

package/README.md

@@ -1,225 +1,99 @@
-# Purpose
+# smartloc
 
-If like me:
-- you are developping a NodeJS API server which requires internationalization.
-- you find most i18n libraries too complicated for your needs, or requiring a refactoring of your existing architecture
-- you find it painful to propagate the request accepted languages in all your application parts
+Internationalization with tagged template strings, for Node APIs and React apps.
 
-... then this library might be for you.
-
-Read a tutorial to learn how to use this lib [here](https://dev.to/oguimbal/i18n-express-apollo-graphql-server-translation-made-simple-33f5)
-
-
-# Framework support
+```ts
+const msg = loc('greeting')`Hello ${name}!`;
+```
 
-There are almost-one-liners integrations with the following frameworks:
+`msg` is not translated yet. It gets translated at the very last moment: when Express sends the response, when GraphQL resolves the field, or when React renders it.
 
-- [Express](https://github.com/apollographql/apollo-server/tree/master/packages/apollo-server-express) => see [this sample](./samples/express/main.ts)
-- [Apollo server express](https://github.com/apollographql/apollo-server/tree/master/packages/apollo-server-express) => see [this sample](./samples/graphql/main.ts)
+## Why smartloc?
 
-# How this works
+- **Your code stays readable.** The source text lives in the code, not in a `keys.json` you have to look up.
+- **No language to pass around.** Build your objects as usual. Translation happens at the boundary, based on `Accept-Language` or the current UI locale.
+- **Server and browser.** Same strings, same API, in Express, Apollo/GraphQL and React.
+- **A CLI does the bookkeeping.** It collects strings from your code and keeps your JSON/XLIFF translation files in sync.
 
-Install it
+## Install
 
 ```bash
-npm install smartloc --save
-```
-
-Just forget manipulating already translated strings in your code. It is cumbersome, and might leak languages you dont understand in your logs.
-
-Smartloc allows you to declare in your code strings like that:
-
-```typescript
-// recommanded: Explicitely specify a string unique ID
-const myString = loc('stringUniqueId')`Hello ${name}, how are you today ?`;
-
-// If you are not affraid of occasionally losing some translations when changing your code,
-// then you can use this simpler form:
-const myString = loc`Hello ${name}, how are you today ?`;
-// => An ID will be autogenerated based on this string hash
-//   => you might lose translations when changing the original string in code.
+npm install smartloc
 ```
 
-Those will give you an instance of `StrLoc` interface.
+## Quick start
 
-Here is how you can use it:
-```typescript
-// build a translatable string
-const name = 'world';
-const str = loc`Hello ${name}`; // nb: This one will have an auto-generated id.
+```ts
+import { loc, setDefaultLocale, addLocale, withLocales } from 'smartloc';
 
-// Just fake loading translations
 setDefaultLocale('en');
-addLocale('fr', {
-    [str.id]: 'Bonjour {0}',
-});
-
-// Use the string without language context (logs, ...)
-console.log(str.toString()); // => Hello world
-console.log(JSON.stringify({msg: str})); // => {"msg": "Hello world"}
-
-// ... or with language context (when returning a query result, ...)
-console.log(withLocales(['it', 'fr'], () => str.toString())); // => Bonjour world
-console.log(withLocales(['it', 'fr'], () => JSON.stringify({msg: str})); // => {"msg": "Bonjour world"}
-```
-
-As you might see, the translation is NOT performed when you build the string, but when you actually try to send a result to your end user.
-
-This allows you to build your app without caring about knowing which language your user accepts.
-The translation will be automatically performed when sending actual json to your user, through a simple middleware (see samples listed in "Framework Support")
-
-
-# Translating your app
-
-## Generating/updating translations from code
-As an example, if you write your code in english, and you would like to translate your app in French and Deutsch, add the following script to your package.json file:
-
-```typescript
-{
-    "scripts": {
-        "smartloc": "smartloc collect --format=json --locales=fr-FR,de-DE --defaultLocale=en-US"
-    }
-}
-```
-
-Once you have written your code (or each time you have changed it), you can run `npm run smartloc` to create/update your translation files.
-
-nb: The `--defaultLocale` argument is optional, and will be infered from your code if you explicitly call `setDefaultLocale()` somewhere.
-
-## Loading available translations on server boot
-
-Before serving any request, you must:
-1) Tell smartloc which is the default locale (the one you wrote your translations in)
-2) Load other locales
+addLocale('fr', { greeting: 'Bonjour {0} !' });
 
-For 1), this is straightforward: `setDefaultLocale('en-US')`
+const msg = loc('greeting')`Hello ${'world'}!`;
 
-To load other locales, you have several options:
-
-### Option 1 - Define in code:
-```typescript
-import {addLocale} from 'smartloc';
-
-// you could also pass here an object loaded from your database, or whatever
-addLocale('fr-FR', {
-    mySentenceId: 'Une traduite en français',
-});
-```
-
-### Option 2 - Load a single given file
-
-```typescript
-import { loadAllLocales } from 'smartloc/node';
-
-await loadAllLocales('/path/to/my-translation.json', true);
+msg.toString();                                       // Hello world!
+withLocales(['fr'], () => msg.toString());            // Bonjour world !
+withLocales(['fr'], () => JSON.stringify({ msg }));   // {"msg":"Bonjour world !"}
 ```
 
-nb: The second argument is 'merge'... if false, all previously loaded translations will be cleared. Else, translations will be merged.
+The ID is optional: ``loc`Hello` `` gets an ID derived from its text. Numbers and dates in placeholders are formatted for the target locale.
 
+## Use it with
 
-### Option 3 - Scan a directory for translations
+### Express
 
-```typescript
-import { loadAllLocales } from 'smartloc/node';
+```ts
+import smartloc from 'smartloc/express';
 
-await loadAllLocales('/path/to/dir/to/scan', true);
+app.use(smartloc());
+app.get('/', (req, res) => res.json({ answer: loc`Hello` }));
 ```
 
-nb: The second argument is 'merge'... if false, all previously loaded translations will be cleared. Else, translations will be merged.
-
-
-
-
-## Supported formats
-
-Smartloc cli implements two translation format through the `--format` argument
-
-- `--format=json` : JSON translation files
-- `--format=xliff` : XLIFF translation files
+`res.json()` and `res.send()` are translated according to the request's `Accept-Language` header. See [docs/express.md](docs/express.md).
 
-nb: Smartloc is grouping your translation IDs by category, detected by the first "." in your ID.
+### GraphQL (Apollo)
 
-# Other use cases
-
-The `LocStr` interface has [several implementations](./src/core/smartloc.ts):
-
-### Smartloc
-The default one which is returned when using the `loc` tag:
-```typescript
-return loc`Hello`;
+```ts
+import { GLocString, localizeSchema, localizedContext } from 'smartloc/graphql';
 ```
 
-### MultiLoc
-If you wish to declare all translations directly in your code:
-```typescript
-return new MultiLoc({
-    en: 'Hello',
-    fr: 'Bonjour',
-});
-```
+Declare fields as `LocalizedString`, wrap your schema and context, and resolvers can return `loc` strings. See [docs/graphql.md](docs/graphql.md).
 
-### SingleLoc
-If you wish to declare a string that is the same in all languages, but which is typed as a `LocStr`:
-```typescript
-return new SingleLoc('Typescript');
-```
+### React
 
-### TransformedLoc
-Sometimes, you will want to apply transformations to your final string.
-You can do that using the `.transform()` method available on `LocStr`, which will return you a transformed translatable string.
+A `loc` string is also a React element. Placeholders can be React nodes.
 
-```typescript
-return loc`Some string wich can contain html`
-        .transform(x => escapeHtml(x)); // apply a transformation
+```tsx
+<h1>{loc('welcome')`Welcome ${<b>{user.name}</b>}`}</h1>
 ```
 
-## Array of LocStr
-When you have an array of smartloc strings that you want to join, you can use the `LocStringArray` class:
-
-```typescript
-const array = new LocStringArray([loc`Hello`, loc`world`]);
+`changeLocale('fr')` re-renders every rendered string. Use `useAsString()` where a plain string is needed. See [docs/react.md](docs/react.md).
 
-const str = array.join(' ').transform(x => x + ' !');
+## Translate your app
 
-console.log(str.toString('en')); // => Hello world !
-console.log(str.toString('fr')); // => Bonjour monde !
+```bash
+npx smartloc collect --format=json --locales=fr,de --defaultLocale=en
 ```
 
-## Serialization in an untranslated form
+This scans your sources and writes one file per locale in `./i18n`. Translate the `target` values, then load them at startup:
 
-Somtimes, you will want to serialize an arbitrary `LocStr` in its untranslated form (to store a localizable sentence in a DB, for instance).
+```ts
+import { loadAllLocales } from 'smartloc/node';   // server
+await loadAllLocales('./i18n');
 
-In this case, you can serialize it like that:
-
-```typescript
-import {loc, MultiLoc, withSerializationContext} from 'smartloc';
-const sampleObject = {
-    reference: loc('stringId')`Hello {world}`,
-    multi: new MultiLoc({ en: 'A string', fr: 'Une chaine' }),
-};
-
-// serialize
-const serialized = withSerializationContext(() => JSON.stringify(sampleObject));
-
-// store ... nb: it will look like {"reference": "i18n/id:stringId", "multi": {"i18n:fr": "A string", "i18n:en": "Une chaine"}}
-storeInDb(serialized);
+import { loadJsonLocale } from 'smartloc';        // browser
+await loadJsonLocale('/i18n/fr.json');
 ```
 
-You can deserialize it back to translatable instance later like that:
+Re-run `collect` whenever your code changes. It keeps existing translations and flags the ones whose source text changed. See [docs/cli.md](docs/cli.md).
 
-```typescript
-import {toLocalizable} from 'smartloc';
-const obj = loadFromDb();
-
-// get back a translatable intance
-const serializable = toLocalizable(obj);
-```
+## Going further
 
-## Cloning
-Beware, if you deep-clone an object containing smartloc string instances, you must:
-- Clone the object prototype
-- Clone symbol properties
+- [docs/api.md](docs/api.md): plurals, locale resolution, `multiLoc`, `singleLoc`, `joinArray`, `transform`
+- [docs/storage.md](docs/storage.md): storing untranslated strings in a database
+- [Tutorial on dev.to](https://dev.to/oguimbal/i18n-express-apollo-graphql-server-translation-made-simple-33f5)
+- [AGENTS.md](AGENTS.md): instructions for AI coding agents using this library
 
-... or you could just ignore cloning smartloc strings altogether (they are immutable anyway): You can detect them using the `isLocStr()` method and skip them when performing your deep clone.
+## License
 
-NB: Of course, if you clone your object using `JSON.parse(JSON.stringify(obj))`, then you will lose translatability (smartloc strings will be translated as strings in your default language).
+MIT

package/core/json-utils.js

@@ -41,7 +41,7 @@ function _toLocalizable(value, depth) {
         }
         return value;
     }
-    if (typeof value !== 'object' || value instanceof Date) {
+    if (typeof value !== 'object' || value instanceof Date || (0, literal_1.isLocStr)(value)) {
         return value;
     }
     // === handle arrays
@@ -62,11 +62,19 @@ function _toLocalizable(value, depth) {
         return value;
     }
     // === handle smartloc with args
-    if (keys.length === 2 && keys.includes('i18n') && keys.includes('data') && typeof value.i18n === 'string' && value.data instanceof Array) {
+    // The native encoder includes count (possibly undefined before stringify).
+    // A counted message can have no interpolation data; JSON then keeps null.
+    if (typeof value.i18n === 'string'
+        && (value.data instanceof Array || value.data === null)
+        && keys.includes('data')
+        && (keys.length === 2 || (keys.length === 3 && keys.includes('count')))
+        && (value.count === undefined || typeof value.count === 'number')) {
         return (0, smartloc_1.smartLoc)({
             id: value.i18n,
             literals: null,
-            placeholders: value.data,
+            // These descriptors can themselves contain messages. Restore them
+            // before rendering so their IDs are not interpolated as literal text.
+            placeholders: _toLocalizable(value.data, depth - 1),
             count: value.count
         });
     }
@@ -136,7 +144,11 @@ function _toJsonStorable(v, depth) {
         return ret || v;
     }
     if ((0, literal_1.isLocStr)(v)) {
-        return v.toJSON();
+        const stored = v.toJSON();
+        // toJSON returns the interpolation values as-is. Convert those while
+        // the serialization scope is still active; later JSON.stringify must
+        // not translate a remaining nested LocStr into a fixed-language string.
+        return stored === v ? v : _toJsonStorable(stored, depth - 1);
     }
     const obj = {};
     let diff = false;

package/core/json-utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"json-utils.js","sourceRoot":"","sources":["../../src/core/json-utils.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"json-utils.js","sourceRoot":"","sources":["../../src/core/json-utils.ts"],"names":[],"mappings":"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"}

package/docs/api.md

@@ -0,0 +1,112 @@
+# Core API
+
+Everything below is exported from `smartloc`.
+
+## Declaring strings
+
+```ts
+import { loc } from 'smartloc';
+
+loc('user.greeting')`Hello ${name}`;   // explicit ID (recommended)
+loc`Hello ${name}`;                    // auto ID: sha1 of the source text
+```
+
+- **Explicit IDs** survive text changes. Use a `.` to namespace them (`user.greeting`): the CLI groups translation files by the part before the first dot.
+- **Auto IDs** change whenever the source text changes, so the translation is lost. Fine for throwaway strings.
+- Placeholders can be strings, numbers, `Date`, other `loc` strings, or React nodes.
+  - Numbers are formatted with `Intl.NumberFormat` for the target locale.
+  - Dates are formatted with `Intl.DateTimeFormat` (day + month + year, plus time when the date has one).
+  - Nested `loc` strings are translated in the same locale.
+- In translation files, placeholders appear as `{0}`, `{1}`, ... in source order.
+
+### Plurals
+
+```ts
+loc.plural(count)('cart.items')`${count} items`;
+```
+
+`count === 1` selects the `singular` form, anything else the `plural` form:
+
+```ts
+addLocale('fr', {
+    'cart.items': { singular: 'Un article', plural: '{0} articles' },
+});
+```
+
+The code only contains the plural form. The singular form of your default language lives in the default-locale translation file. Generate it with `--defaultLocale` and load it like any other locale.
+
+### `loc.nocollect`
+
+Same as `loc`, but the CLI ignores it. Useful for formatting helpers.
+
+## Locales
+
+```ts
+import { setDefaultLocale, addLocale, changeLocale, removeLocale, clearLocales } from 'smartloc';
+
+setDefaultLocale('en');                     // the language you write code in (required)
+addLocale('fr-FR', { id: 'Texte {0}' });    // register translations
+addLocale('fr-FR', { other: '...' }, true); // merge into an existing locale
+changeLocale('fr-FR');                      // switch the current locale (UI apps)
+removeLocale('fr-FR');
+clearLocales();
+```
+
+Locale IDs are case-insensitive. `fr-FR` also registers `fr` when no `fr` exists, so a request for `fr-CA` falls back to it.
+
+Prefer the CLI-generated files over hand-written `addLocale` calls: see [cli.md](cli.md).
+
+## Getting a translation
+
+```ts
+const s = loc('id')`Hello`;
+
+s.toString();                       // resolved from context (see below)
+s.toString('fr');                   // force a locale
+withLocales(['fr-CA', 'fr'], () => s.toString());   // Accept-Language style list
+JSON.stringify({ s });              // toJSON() translates like toString()
+```
+
+Resolution order for `toString()`:
+
+1. The locale passed as argument.
+2. The `withLocales()` list, first locale that has the string.
+3. The current locale set with `changeLocale()`.
+4. The default locale (in-code text).
+
+`withLocales` is what the Express and GraphQL integrations call for you.
+
+### Translating whole objects
+
+```ts
+import { translateObject, translateInContext } from 'smartloc';
+
+translateObject('fr', { title: loc`Hello`, items: [loc`A`] });   // { title: 'Bonjour', items: ['A'] }
+withLocales(['fr'], () => translateInContext(obj));               // same, using ambient context
+```
+
+Both return a copy only when something changed. Typed as `TranslationOf<T>`.
+
+## Other kinds of strings
+
+All of them implement the same `LocStr` interface as `loc`.
+
+```ts
+import { singleLoc, multiLoc, joinArray } from 'smartloc';
+
+singleLoc('TypeScript');                        // same text in every language
+multiLoc({ en: 'Hello', fr: 'Bonjour' });        // translations declared inline
+joinArray(', ', [loc`Red`, loc`Blue`]);          // translated join; separator may be a LocStr too
+loc`<b>Hi</b>`.transform(escapeHtml);            // post-process the translated text
+```
+
+`transform()` results cannot be stored (see [storage.md](storage.md)) and render as their parent in React.
+
+## Utilities
+
+- `isLocStr(value)`: type guard for any `LocStr`.
+- `getDefaultLocale()`: the locale set with `setDefaultLocale`.
+
+## Cloning objects that contain `LocStr`
+
+`LocStr` instances are frozen objects tagged with a symbol. A deep clone must copy the prototype and symbol properties, or simply skip values where `isLocStr(v)` is true (they are immutable). `JSON.parse(JSON.stringify(obj))` turns them into plain, default-language strings.

package/docs/cli.md

@@ -0,0 +1,85 @@
+# CLI: collecting and loading translations
+
+## `smartloc collect`
+
+Scans your sources for `loc` strings and writes one translation file per locale.
+
+```bash
+npx smartloc collect --format=json --locales=fr,de --defaultLocale=en
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `--locales` | required | Comma-separated locales to generate, other than the default one. |
+| `--defaultLocale` | inferred | Language of the in-code text. Inferred from `setDefaultLocale('xx')` in sources when omitted. When given, also writes the default-locale file (needed for plurals and for stored strings, see below). |
+| `--format` | `xliff` | `json` or `xliff`. |
+| `--outDir` | `i18n` | Output directory. |
+| `--source` | `.` | Directory to scan. `.js`, `.ts`, `.jsx`, `.tsx` files; `.gitignore` is honored. |
+| `--additionalSimpleTag` | | Also collect strings matching a pattern, `*` being the string. Example: `Named<*>` collects `Named<'text'>`. |
+
+Add it to `package.json` and run it whenever code changes:
+
+```json
+{ "scripts": { "i18n": "smartloc collect --format=json --locales=fr,de --defaultLocale=en" } }
+```
+
+### What a run does
+
+- New strings are added with an empty `target`.
+- Strings that disappeared from code are removed. If a string with the same text reappears under another ID, its translation is moved.
+- Strings whose source text changed keep their translation but are marked `"dirty": true`.
+- The command prints, per locale, how many translations are missing, dirty, or identical to the source.
+
+### File format (JSON)
+
+`i18n/fr.json`:
+
+```json
+{
+    "sourceLanguage": "en",
+    "targetLanguage": "fr",
+    "resources": {
+        "$default": {
+            "sha1.b128...": { "source": "Auto id", "target": null }
+        },
+        "cart": {
+            "items": {
+                "source": { "singular": null, "plural": "{0} items" },
+                "target": { "singular": "Un article", "plural": "{0} articles" }
+            }
+        }
+    }
+}
+```
+
+- IDs are grouped by namespace: the part before the first `.`. Strings without a dot go under `$default`.
+- Fill in `target`. A `null` target falls back to the next locale, then to the default language.
+- Plural entries hold `{ singular, plural }`. `singular` is used when the count is exactly 1.
+- `--format=xliff` writes the same data as XLIFF. JSON is the recommended format: the XLIFF writer currently uses the `.json` extension, which the loaders do not recognize as XLIFF.
+
+## Loading translations
+
+### Node
+
+```ts
+import { loadAllLocales, loadLocale } from 'smartloc/node';
+
+await loadAllLocales('./i18n');              // every file in the directory
+await loadLocale('./i18n/fr.json');          // one file
+await loadAllLocales('./more', true);        // merge into already loaded locales
+```
+
+Without `merge`, loading a locale that already exists throws.
+
+### Browser
+
+```ts
+import { loadJsonLocale } from 'smartloc';
+
+await loadJsonLocale('/i18n/fr.json');       // fetch() then register
+loadJsonLocale(importedJsonObject);          // or pass the parsed object
+```
+
+### Default locale file
+
+Load the default-locale file too (`i18n/en.json`) when you use plurals, or when you deserialize stored strings (see [storage.md](storage.md)). It is the only place holding the singular form of your default language.

package/docs/express.md

@@ -0,0 +1,36 @@
+# Express
+
+```ts
+import express from 'express';
+import { loc, setDefaultLocale } from 'smartloc';
+import smartloc from 'smartloc/express';
+import { loadAllLocales } from 'smartloc/node';
+
+setDefaultLocale('en');
+const ready = loadAllLocales('./i18n');
+
+const app = express();
+app.use(smartloc({ waitFor: ready }));
+
+app.get('/', (req, res) => res.json({ answer: loc('hello')`Hello world` }));
+app.get('/:name', (req, res) => res.send(loc('hi')`Hi ${req.params.name}`));
+```
+
+The middleware wraps `res.json()`, `res.jsonp()` and `res.send()` so that everything they serialize is translated for the request's `Accept-Language` header. Requests without that header get the default language.
+
+## Options
+
+```ts
+smartloc({
+    // Promise to await before translating (e.g. locale loading)
+    waitFor: ready,
+
+    // Pick the locale yourself; falls back to Accept-Language when it returns nothing
+    customLocaleResolver: req => req.user?.language,   // string, string[], or a Promise of those
+
+    // Called when the resolver throws; the request is then served untranslated
+    errorLogger: err => console.error(err),
+});
+```
+
+Full runnable example: [samples/express/main.ts](../samples/express/main.ts).

package/docs/graphql.md

@@ -0,0 +1,37 @@
+# GraphQL (Apollo Server + Express)
+
+```ts
+import { ApolloServer } from 'apollo-server-express';
+import { GraphQLSchema, GraphQLObjectType } from 'graphql';
+import { loc, setDefaultLocale } from 'smartloc';
+import { GLocString, localizeSchema, localizedContext } from 'smartloc/graphql';
+
+setDefaultLocale('en');
+
+const schema = new GraphQLSchema({
+    query: new GraphQLObjectType({
+        name: 'Root',
+        fields: () => ({
+            hello: {
+                type: GLocString,                          // exposed as `LocalizedString`
+                resolve: () => loc('hello')`Hello world`,
+            },
+        }),
+    }),
+});
+
+const apollo = new ApolloServer({
+    schema: localizeSchema(schema),
+    context: localizedContext(async ({ req }) => ({ /* your context */ })),
+});
+```
+
+Three pieces:
+
+- **`GLocString`**: a `LocalizedString` scalar. Resolvers return any `LocStr`. As an input, it accepts a plain string (`singleLoc`) or `{ "en": "...", "fr": "..." }` (`multiLoc`).
+- **`localizeSchema(schema)`**: patches resolvers of `LocalizedString` fields, and of `JSON`/`JSONObject` scalar fields, so their result is translated. Call it once on your built schema.
+- **`localizedContext(fn)`**: wraps your context factory and reads `Accept-Language` from the request. If you build the context yourself, tag it with `localizedContextObject(ctx, ['fr', 'en'])` instead.
+
+`JSON` fields are translated recursively, so an object containing `loc` strings can be returned as-is.
+
+Full runnable example: [samples/graphql/main.ts](../samples/graphql/main.ts).

package/docs/react.md

@@ -0,0 +1,52 @@
+# React
+
+Every `LocStr` is also a valid React element. Render it directly:
+
+```tsx
+import { loc, setDefaultLocale, changeLocale, loadJsonLocale } from 'smartloc';
+
+setDefaultLocale('en');
+await loadJsonLocale('/i18n/fr.json');
+
+function Welcome({ user }) {
+    return <h1>{loc('welcome')`Welcome ${<b>{user.name}</b>}`}</h1>;
+}
+```
+
+- Placeholders can be React nodes. They are kept as nodes when rendered, so the translation `Bienvenue {0} !` yields `Bienvenue <b>Alice</b> !`.
+- `changeLocale('fr')` re-renders every mounted `loc` string. No provider or context needed.
+- Numbers and dates in placeholders are formatted for the active locale.
+
+## Strings where an element is not allowed
+
+Attributes such as `placeholder`, `title` or `aria-label` need a plain string. Use the hook, which re-renders on locale change:
+
+```tsx
+import { useAsString } from 'smartloc';
+
+function Search() {
+    const hint = useAsString(loc('search.hint')`Type to search`);
+    return <input placeholder={hint} />;
+}
+```
+
+`useAsString` accepts a `LocStr`, a plain string, `null` or `undefined`. The same hook exists as a method: `loc`...`.useAsString()`.
+
+Outside components, `.toString()` gives the text for the current locale.
+
+## Switching language
+
+```tsx
+<select onChange={e => changeLocale(e.target.value)}>
+    <option value="en">English</option>
+    <option value="fr">Français</option>
+</select>
+```
+
+The locale must be loaded first (`loadJsonLocale` or `addLocale`), otherwise `changeLocale` throws. Pass `false` as second argument to get `'not found'` instead.
+
+## Notes
+
+- `transform()` results render as their untransformed parent (with a console warning). Apply transformations to the string from `useAsString()` instead.
+- `joinArray()` renders its items and separators as a fragment.
+- React 19 is a peer dependency. Server-side rendering works with `renderToString`.

package/docs/storage.md

@@ -0,0 +1,57 @@
+# Storing untranslated strings
+
+Sometimes a `LocStr` must be persisted (a DB record, a queue message) and translated later, when it is finally shown to a user.
+
+## Store
+
+```ts
+import { loc, multiLoc, toJsonStorable } from 'smartloc';
+
+const record = {
+    title: loc('doc.title')`Report for ${customer}`,
+    status: multiLoc({ en: 'Draft', fr: 'Brouillon' }),
+    plain: 'Untouched',
+};
+
+const stored = JSON.stringify(toJsonStorable(record));
+// {"title":{"i18n":"doc.title","data":["Acme"]},"status":{"i18n:en":"Draft","i18n:fr":"Brouillon"},"plain":"Untouched"}
+```
+
+`toJsonStorable` walks objects and arrays recursively. Plain values, `Date`s and nested `LocStr` placeholders are preserved. Plural counts are stored too.
+
+`withSerializationContext(() => JSON.stringify(record))` does the same for a direct `JSON.stringify`.
+
+### Stored forms
+
+| Kind | Stored as |
+|---|---|
+| `loc` without placeholders | `"i18n/id:doc.title"` |
+| `loc` with placeholders or plural | `{ "i18n": "doc.title", "data": [...], "count": n }` |
+| `singleLoc` | `"i18n/single:text"` |
+| `multiLoc` | `{ "i18n:en": "...", "i18n:fr": "..." }` |
+| `transform()` / `joinArray()` | not supported, throws |
+
+### Options
+
+```ts
+toJsonStorable(record, { nonSelfDescriptive: 'toMulti' });
+```
+
+- `'id'` (default): store the ID. The reader must have the same translations loaded.
+- `'toMulti'`: expand into every loaded locale, stored as a `multiLoc`. Self-contained, but not updated when translations change.
+- `'skip'`: leave `loc` strings as-is, so `JSON.stringify` translates them in the current locale.
+
+## Restore
+
+```ts
+import { toLocalizable, jsonParseLocalized } from 'smartloc';
+
+const record = toLocalizable(JSON.parse(stored));   // from a parsed value
+const record = jsonParseLocalized(stored);          // from the JSON text
+```
+
+The result contains `LocStr` instances again, ready for `withLocales`, Express, GraphQL or React.
+
+Restored `loc` strings no longer carry their in-code text. The default locale must therefore be loaded as a regular translation file (generate it with `smartloc collect --defaultLocale=en`, see [cli.md](cli.md)), otherwise translating them in the default language throws.
+
+Dates become ISO strings through JSON and are not converted back.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "smartloc",
-  "version": "2.0.9",
-  "description": "A i18n toolset for nodejs apis leveraging tagged strings",
+  "version": "2.0.11",
+  "description": "i18n with tagged template strings, for Node APIs (Express, GraphQL) and React apps",
   "main": "index.js",
   "bin": {
     "smartloc": "cli/cli.js"
@@ -16,8 +16,8 @@
     "tagged-string-template",
     "graphql",
     "translation",
-    "internationalization",
-    "typescript"
+    "typescript",
+    "react"
   ],
   "author": "Olivier Guimbal",
   "license": "MIT",
@@ -37,5 +37,13 @@
     "express": "~4.17.1",
     "graphql": "0.13.2",
     "react": "^19"
+  },
+  "agents": {
+    "skills": [
+      {
+        "name": "smartloc",
+        "path": "./skills/smartloc"
+      }
+    ]
   }
 }

package/skills/smartloc/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: smartloc
+description: Use when adding or changing user-facing text in a project that depends on the smartloc i18n library (tagged template strings, Express/GraphQL/React), or when generating and loading its translation files.
+---
+
+# smartloc
+
+Read `AGENTS.md` at the root of the `smartloc` package (`node_modules/smartloc/AGENTS.md`) for the rules and API table. Full docs are in `node_modules/smartloc/docs/`:
+
+- `api.md`: `loc`, plurals, locale resolution, other string kinds
+- `cli.md`: `smartloc collect`, file format, loading
+- `express.md`, `graphql.md`, `react.md`: integrations
+- `storage.md`: persisting untranslated strings
+
+## Workflow for new user-facing text
+
+1. Write ``loc('namespace.id')`Text with ${placeholders}` `` in code. Never pre-translate or concatenate.
+2. In React, render the `LocStr` directly; use `useAsString()` only for string-only props.
+3. Run the project's collect script (look for `smartloc collect` in `package.json`), or `npx smartloc collect --format=json --locales=<locales> --defaultLocale=<default>`.
+4. Fill the new `target` entries in `i18n/<locale>.json`. Leave `source` untouched.
+5. Do not commit `i18n` if the project ignores it; check `.gitignore`.
+
+## Quick checks
+
+- `setDefaultLocale('xx')` must run once at startup, with a literal locale string.
+- Translated output only appears inside `withLocales()`, the Express/GraphQL integrations, or React rendering.
+- Plurals: `loc.plural(n)('id')`...``, and the default-locale file must be generated and loaded.