locon 1.6.0 → 1.6.1

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 1.6.1
+
+### Added
+
+- `L` and `LProps` from `locon/react`: localized source-language text without
+  extra DOM elements, including use inside SVG `<text>`.
+- `L` supports interpolation, CLDR plurals, per-call locale overrides, fallback,
+  and optional `assetKey` disambiguation. React escapes the translated text.
+- The asset checker recognizes `<L>` alongside `<LText>`, including static
+  string-expression children used with placeholders.
+
+### Documentation
+
+- Source-phrase examples for React web and Node; phrase-indexed JSON examples
+  preserve lazy loading without preloading the source locale.
+- Updated website examples and release instructions for 1.6.1.
+
 ## 1.6.0
 
 ### Added

package/README.md

@@ -16,7 +16,7 @@ load browser languages only when they are selected.
 | React web (React 19+) | `locon/react` | Async loaders, provider and reactive hook |
 | Node / plain TypeScript | `locon/core` | Standalone translator and lazy resource store |
 
-**New in 1.6:** platform-specific entries and lazy resources. See
+**New in 1.6.1:** the React web `<L>` component. Version 1.6 introduced platform-specific entries and lazy resources. See
 [React (web), Node and lazy resources](#react-web-node-and-lazy-resources).
 The existing React Native entry remains compatible.
 
@@ -833,8 +833,46 @@ selection won. Failed loads reject, preserve the displayed language and can be
 retried. Parallel loads are deduplicated. Catch rejections in event handlers and
 offer a retry. Local storage and document `lang` remain application decisions.
 Only already loaded resources participate in per-key fallback: the store never
-silently downloads every fallback language. Prefer stable translation keys in
-lazy apps; source-phrase reverse lookup needs the source resources loaded.
+silently downloads every fallback language. Write source-language text in code.
+For lazy apps, use the source phrases as JSON keys so translating them does not
+require downloading the source locale first:
+
+```json
+// en.json
+{ "Überraschung öffnen": "Open your surprise" }
+```
+
+```json
+// de.json
+{ "Überraschung öffnen": "Überraschung öffnen" }
+```
+
+Set `projectLocale: 'de'` for German source strings. Reverse lookup against
+separate technical keys still needs the source resource loaded.
+
+#### Localized React text (`L`, 1.6.1+)
+
+```tsx
+import { L, useLocon } from 'locon/react'
+
+function Card({ name }: { name: string }) {
+  const { l } = useLocon()
+  return <>
+    <button><L>Überraschung öffnen</L></button>
+    <h2><L params={{ name }}>{'Buh, {name}!'}</L></h2>
+    <input placeholder={l('Name eingeben')} />
+  </>
+}
+```
+
+`L` renders a text fragment without a wrapping span. Use it inside HTML or SVG
+text elements. It updates when the provider's locale changes. Pass one source
+string as children; put dynamic values in `params` instead of JSX concatenation
+or nested markup. `count`, `locale`, and `fallback` have the same meaning as in
+`l()`. An optional `assetKey` can disambiguate identical source phrases; missing
+translations fall back to the children unless `fallback` is explicitly set.
+Keep `l()` for string props, document metadata, and other non-rendered values.
+The existing React Native `LText` API is unchanged.
 
 In Node, create an instance per request, pass the request's language preferences
 explicitly, and await `setLocale` before rendering. For resources already loaded

package/dist/react.d.mts

@@ -1,7 +1,7 @@
-import { a as LoconInstance, T as TranslateOptions } from './resources-BwFIzg3m.mjs';
-export { R as ResourceLoader, b as ResourceOptions, c as createLocon, m as matchLocale } from './resources-BwFIzg3m.mjs';
 import * as react from 'react';
 import { PropsWithChildren } from 'react';
+import { T as TranslateOptions, a as LoconInstance } from './resources-BwFIzg3m.mjs';
+export { R as ResourceLoader, b as ResourceOptions, c as createLocon, m as matchLocale } from './resources-BwFIzg3m.mjs';
 
 declare function LoconProvider({ instance, children }: PropsWithChildren<{
     instance: LoconInstance;
@@ -15,5 +15,13 @@ declare function useLocon(): {
     ready: boolean;
     error: Error | null;
 };
+interface LProps extends TranslateOptions {
+    /** Plain text in the project/default language; use params for dynamic values. */
+    children: string;
+    /** Only needed to disambiguate identical source phrases. */
+    assetKey?: string;
+}
+/** Localized text without an extra DOM element, also usable inside SVG text. */
+declare function L({ children, assetKey, ...options }: LProps): react.JSX.Element;
 
-export { LoconInstance, LoconProvider, useLocon };
+export { L, type LProps, LoconInstance, LoconProvider, useLocon };

package/dist/react.d.ts

@@ -1,7 +1,7 @@
-import { a as LoconInstance, T as TranslateOptions } from './resources-BwFIzg3m.js';
-export { R as ResourceLoader, b as ResourceOptions, c as createLocon, m as matchLocale } from './resources-BwFIzg3m.js';
 import * as react from 'react';
 import { PropsWithChildren } from 'react';
+import { T as TranslateOptions, a as LoconInstance } from './resources-BwFIzg3m.js';
+export { R as ResourceLoader, b as ResourceOptions, c as createLocon, m as matchLocale } from './resources-BwFIzg3m.js';
 
 declare function LoconProvider({ instance, children }: PropsWithChildren<{
     instance: LoconInstance;
@@ -15,5 +15,13 @@ declare function useLocon(): {
     ready: boolean;
     error: Error | null;
 };
+interface LProps extends TranslateOptions {
+    /** Plain text in the project/default language; use params for dynamic values. */
+    children: string;
+    /** Only needed to disambiguate identical source phrases. */
+    assetKey?: string;
+}
+/** Localized text without an extra DOM element, also usable inside SVG text. */
+declare function L({ children, assetKey, ...options }: LProps): react.JSX.Element;
 
-export { LoconInstance, LoconProvider, useLocon };
+export { L, type LProps, LoconInstance, LoconProvider, useLocon };

package/dist/react.js

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/react/index.tsx
 var react_exports = {};
 __export(react_exports, {
+  L: () => L,
   LoconProvider: () => LoconProvider,
   createLocon: () => createLocon,
   matchLocale: () => matchLocale,
@@ -319,8 +320,13 @@ function useLocon() {
   const snapshot = (0, import_react.useSyncExternalStore)(instance.subscribe, instance.getSnapshot, instance.getSnapshot);
   return { ...snapshot, locales: instance.locales, l: instance.l, setLocale: instance.setLocale };
 }
+function L({ children, assetKey, ...options }) {
+  const { l } = useLocon();
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_jsx_runtime.Fragment, { children: l(assetKey ?? children, { ...options, fallback: options.fallback ?? children }) });
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  L,
   LoconProvider,
   createLocon,
   matchLocale,

package/dist/react.mjs

@@ -281,7 +281,7 @@ function createLocon(options) {
 }
 
 // src/react/index.tsx
-import { jsx } from "react/jsx-runtime";
+import { Fragment, jsx } from "react/jsx-runtime";
 var Context = createContext(null);
 function LoconProvider({ instance, children }) {
   return /* @__PURE__ */ jsx(Context, { value: instance, children });
@@ -292,7 +292,12 @@ function useLocon() {
   const snapshot = useSyncExternalStore(instance.subscribe, instance.getSnapshot, instance.getSnapshot);
   return { ...snapshot, locales: instance.locales, l: instance.l, setLocale: instance.setLocale };
 }
+function L({ children, assetKey, ...options }) {
+  const { l } = useLocon();
+  return /* @__PURE__ */ jsx(Fragment, { children: l(assetKey ?? children, { ...options, fallback: options.fallback ?? children }) });
+}
 export {
+  L,
   LoconProvider,
   createLocon,
   matchLocale,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "locon",
-  "version": "1.6.0",
+  "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",

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 })
   }