locon 1.5.1 → 1.6.1

package/dist/resources-BwFIzg3m.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Per-call options for `l()`, `lIn()` and `<LText>`.
+ *
+ * All four are optional and independent: `params` interpolates, `count`
+ * selects a plural form, and `locale` renders one call in a language other
+ * than the current one (used when an app exports a document in a language
+ * the interface is not currently showing). `fallback` is returned only when
+ * no locale resolves the input.
+ */
+interface TranslateOptions {
+    /** Values for `{token}` placeholders inside the resolved string. */
+    params?: Record<string, string | number>;
+    /** Selects `key_one` / `key_few` / `key_other` … via `Intl.PluralRules`. */
+    count?: number;
+    /** Resolve against this locale instead of the current one. */
+    locale?: string;
+    /** Human-readable fallback when no locale resolves the key/value. */
+    fallback?: string;
+}
+
+type Resource = Record<string, string>;
+type ResourceLoader = () => Promise<Resource | {
+    default: Resource;
+}>;
+interface ResourceOptions {
+    loaders: Record<string, ResourceLoader>;
+    defaultLocale: string;
+    projectLocale?: string;
+    locale?: string | null;
+    /** Ordered browser/device preferences, or an explicit list in Node. */
+    languages?: readonly string[];
+}
+interface LocaleSnapshot {
+    currentLocale: string;
+    loading: boolean;
+    ready: boolean;
+    error: Error | null;
+}
+/** First matching preference wins; regional variants can use a base resource. */
+declare function matchLocale(languages: readonly string[], supported: readonly string[], fallback: string): string;
+/** A per-app/per-request store. Importing it touches neither React nor a platform API. */
+declare function createLocon(options: ResourceOptions): {
+    locales: string[];
+    l: (key: string, translateOptions?: TranslateOptions) => string;
+    loadLocale: (locale: string) => Promise<Resource>;
+    setLocale: (locale: string | null) => Promise<boolean>;
+    getSnapshot: () => LocaleSnapshot;
+    subscribe(listener: () => void): () => void;
+};
+type LoconInstance = ReturnType<typeof createLocon>;
+
+export { type LocaleSnapshot as L, type ResourceLoader as R, type TranslateOptions as T, type LoconInstance as a, type ResourceOptions as b, createLocon as c, matchLocale as m };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "locon",
-  "version": "1.5.1",
-  "description": "locon is a simple and lightweight library for React Native that provides a simple way to manage translations in your app.",
+  "version": "1.6.1",
+  "description": "Lightweight localization for React Native, React and Node with lazy locale resources.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
@@ -10,17 +10,28 @@
       "default": "./dist/index.js"
     },
     "./skills/*": "./skills/*",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./core": {
+      "types": "./dist/core.d.ts",
+      "import": "./dist/core.mjs",
+      "require": "./dist/core.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.mjs",
+      "require": "./dist/react.js"
+    }
   },
   "files": [
     "dist",
-    "skills"
+    "skills",
+    "CHANGELOG.md"
   ],
   "scripts": {
-    "build": "tsup",
+    "build": "tsup && tsup --config tsup.web.config.ts",
     "lint": "eslint src",
-    "prepare": "tsup",
-    "pretest": "tsup",
+    "prepare": "npm run build",
+    "pretest": "npm run build",
     "test": "jest"
   },
   "keywords": [
@@ -59,6 +70,12 @@
     },
     "react-native-localize": {
       "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-native": {
+      "optional": true
     }
   },
   "devDependencies": {

package/skills/locon-sync/SKILL.md

@@ -36,7 +36,7 @@ node "$LOCON_SYNC_SKILL_DIR/scripts/check-locon-assets.mjs" \
 ```
 
 This scans static strings in JavaScript/TypeScript (single, double, or template
-quotes), `lIn()` calls and `LText` children/`assetKey` props. It ignores calls
+quotes), `lIn()` calls and `LText` / `L` children and `assetKey` props. It ignores calls
 inside comments and string examples. Orphaned keys and plural categories that
 currently fall back to `_other` are advisory because static analysis cannot
 prove either is wrong. Enforce them in CI with `--strict-orphans` and
@@ -129,6 +129,19 @@ When extracting phrases from source, remember **JSX collapses whitespace**: a
 multi-line `<LText>` child becomes one space-joined string at runtime, so the
 asset value must match the collapsed form.
 
+For React web (locon 1.6.1+), use `L` from `locon/react` for text children:
+
+```tsx
+<button><L>Überraschung öffnen</L></button>
+<h2><L params={{ name }}>{'Buh, {name}!'}</L></h2>
+<input placeholder={l('Name eingeben')} />
+```
+
+`L` adds no DOM element and works inside SVG `<text>`. Pass one source string,
+not nested markup or interpolated JSX children. Use `l()` for string props,
+metadata, and other non-rendered values. Use source phrases as resource keys
+when lazy loading must work without loading the source locale first.
+
 ## 5. Beyond the strings
 
 Shipping a language is more than its JSON. Check whether the project needs:

package/skills/locon-sync/scripts/check-locon-assets.mjs

@@ -7,7 +7,7 @@
  * language to someone who cannot read it. Nothing else in a typical toolchain
  * catches that, or any of the other failure modes below.
  *
- *   1. every phrase passed to `l()` / `<LText>` resolves
+ *   1. every phrase passed to `l()` / `<LText>` / `<L>` resolves
  *   2. every locale has exactly the keys the source locale has
  *   3. placeholders match (with a documented exception for plurals)
  *   4. no unreachable duplicate values
@@ -376,23 +376,32 @@ for (const file of files) {
     if (literal) used.push({ phrase: literal.value, file })
   }
 
-  for (const match of executable.matchAll(/<LText\b([^>]*)>([\s\S]*?)<\/LText>/g)) {
+  for (const match of executable.matchAll(/<(LText|L)\b([^>]*)>([\s\S]*?)<\/\1>/g)) {
+    const tag = match[1]
     const openingTagEnd = match[0].indexOf('>')
-    const attributes = code.slice(match.index + '<LText'.length, match.index + openingTagEnd)
+    const attributes = code.slice(match.index + tag.length + 1, match.index + openingTagEnd)
     const childStart = match.index + openingTagEnd + 1
-    const childEnd = match.index + match[0].length - '</LText>'.length
+    const childEnd = match.index + match[0].length - tag.length - 3
     const child = code.slice(childStart, childEnd)
     const assetKey = attributeLiteral(attributes, 'assetKey')
 
     if (assetKey) {
       used.push({ phrase: assetKey, file, directKey: true })
-    } else if (!/[<>{}]/.test(match[2])) {
+    } else if (!/[<>{}]/.test(child)) {
       used.push({ phrase: collapse(child), file })
+    } else {
+      // A single literal expression preserves placeholders: <L>{'Hi {name}'}</L>.
+      const expression = child.trim()
+      if (expression.startsWith('{') && expression.endsWith('}')) {
+        const contents = expression.slice(1, -1).trim()
+        const literal = readLiteralAt(contents, 0)
+        if (literal && !contents.slice(literal.end).trim()) used.push({ phrase: literal.value, file })
+      }
     }
   }
 
-  for (const match of executable.matchAll(/<LText\b([^>]*)\/>/g)) {
-    const attributes = code.slice(match.index + '<LText'.length, match.index + match[0].length - 2)
+  for (const match of executable.matchAll(/<(LText|L)\b([^>]*)\/>/g)) {
+    const attributes = code.slice(match.index + match[1].length + 1, match.index + match[0].length - 2)
     const assetKey = attributeLiteral(attributes, 'assetKey')
     if (assetKey) used.push({ phrase: assetKey, file, directKey: true })
   }