smartloc 2.0.10 → 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,250 +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}',
-});
+addLocale('fr', { greeting: 'Bonjour {0} !' });
 
-// Use the string without language context (logs, ...)
-console.log(str.toString()); // => Hello world
-console.log(JSON.stringify({msg: str})); // => {"msg": "Hello world"}
+const msg = loc('greeting')`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"}
+msg.toString();                                       // Hello world!
+withLocales(['fr'], () => msg.toString());            // Bonjour world !
+withLocales(['fr'], () => JSON.stringify({ msg }));   // {"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.
+The ID is optional: ``loc`Hello` `` gets an ID derived from its text. Numbers and dates in placeholders are formatted for the target locale.
 
-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")
+## Use it with
 
+### Express
 
-# Translating your app
+```ts
+import smartloc from 'smartloc/express';
 
-## 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"
-    }
-}
+app.use(smartloc());
+app.get('/', (req, res) => res.json({ answer: loc`Hello` }));
 ```
 
-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
-
-For 1), this is straightforward: `setDefaultLocale('en-US')`
+`res.json()` and `res.send()` are translated according to the request's `Accept-Language` header. See [docs/express.md](docs/express.md).
 
-To load other locales, you have several options:
+### GraphQL (Apollo)
 
-### 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',
-});
+```ts
+import { GLocString, localizeSchema, localizedContext } from 'smartloc/graphql';
 ```
 
-### Option 2 - Load a single given file
-
-```typescript
-import { loadAllLocales } from 'smartloc/node';
-
-await loadAllLocales('/path/to/my-translation.json', true);
-```
+Declare fields as `LocalizedString`, wrap your schema and context, and resolvers can return `loc` strings. See [docs/graphql.md](docs/graphql.md).
 
-nb: The second argument is 'merge'... if false, all previously loaded translations will be cleared. Else, translations will be merged.
+### React
 
+A `loc` string is also a React element. Placeholders can be React nodes.
 
-### Option 3 - Scan a directory for translations
-
-```typescript
-import { loadAllLocales } from 'smartloc/node';
-
-await loadAllLocales('/path/to/dir/to/scan', true);
+```tsx
+<h1>{loc('welcome')`Welcome ${<b>{user.name}</b>}`}</h1>
 ```
 
-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
-
-nb: Smartloc is grouping your translation IDs by category, detected by the first "." in your ID.
+`changeLocale('fr')` re-renders every rendered string. Use `useAsString()` where a plain string is needed. See [docs/react.md](docs/react.md).
 
-# Other use cases
+## Translate your app
 
-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`;
-```
-
-### MultiLoc
-If you wish to declare all translations directly in your code:
-```typescript
-return new MultiLoc({
-    en: 'Hello',
-    fr: 'Bonjour',
-});
-```
-
-### 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');
-```
-
-### 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.
-
-```typescript
-return loc`Some string wich can contain html`
-        .transform(x => escapeHtml(x)); // apply a transformation
-```
-
-## 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`]);
-
-const str = array.join(' ').transform(x => x + ' !');
-
-console.log(str.toString('en')); // => Hello world !
-console.log(str.toString('fr')); // => Bonjour monde !
-```
-
-## Serialization in an untranslated form
-
-Somtimes, you will want to serialize an arbitrary `LocStr` in its untranslated form (to store a localizable sentence in a DB, for instance).
-
-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);
-```
-
-You can deserialize it back to translatable instance later like that:
-
-```typescript
-import {toLocalizable} from 'smartloc';
-const obj = loadFromDb();
-
-// get back a translatable intance
-const serializable = toLocalizable(obj);
+```bash
+npx smartloc collect --format=json --locales=fr,de --defaultLocale=en
 ```
 
-### Recursive object conversion
-
-`toJsonStorable(value)` recursively converts messages in objects and arrays to
-untranslated storage values. Serialize that result with `JSON.stringify` when
-storage requires JSON text. `toLocalizable` accepts the already parsed value:
+This scans your sources and writes one file per locale in `./i18n`. Translate the `target` values, then load them at startup:
 
-```typescript
-import { loc, toJsonStorable, toLocalizable } from 'smartloc';
+```ts
+import { loadAllLocales } from 'smartloc/node';   // server
+await loadAllLocales('./i18n');
 
-const value = { labels: ['Custom text', loc('save')`Save`, ''] };
-const stored = JSON.stringify(toJsonStorable(value));
-const restored = toLocalizable(JSON.parse(stored));
+import { loadJsonLocale } from 'smartloc';        // browser
+await loadJsonLocale('/i18n/fr.json');
 ```
 
-Plain strings remain strings. Version 2.0.10 also preserves plural counts and
-recursively converts messages used as interpolation values, in both directions.
-Stored ID references require loaded catalogs, including the default-language
-catalog; source templates are not included. These changes keep the existing
-stored representation.
+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).
 
-`toJsonStorable` leaves ordinary `Date` values intact until JSON serialization.
-JSON turns them into ISO strings; `toLocalizable` does not infer dates from those
-strings, including inside message interpolations. React elements and
-joined/transformed messages are not supported storage values.
+## 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/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.10",
-  "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.