langsys-js-react 0.6.6 → 0.7.0

package/dist/babel.d.mts

@@ -0,0 +1,122 @@
+import { types, PluginObj, PluginPass } from '@babel/core';
+
+/**
+ * langsys-js-react/babel — the placeholder transform (spec VAR-6), as a Babel plugin.
+ *
+ * A value interpolated into translated text becomes a named placeholder, and the value travels as
+ * its param, so one sentence registers once however many users it is shown to (VAR-1):
+ *
+ *   <Translate>Hello {user.name}</Translate>
+ *     → <Translate params={{ name: user.name }}>Hello %name%</Translate>
+ *
+ *   t(`You have ${items.length} items`)
+ *     → t('You have {items_count} items', undefined, { items_count: items.length })
+ *
+ * A subtree the core shows as written — `<DontTranslate>`, a host element with `translate="no"` or
+ * `data-notrans`, or code and notation (`<template>`, `<noscript>`, `<math>`) — is never translated:
+ * a phrase keys it as one opaque element and restores its content, and a block keeps it in its
+ * stored content. A value there therefore stays where it is, in both components, and is marked as a
+ * value (VAR-3) rather than replaced, so the page shows the value and a block's stored content holds
+ * its placeholder; where no marker can stand (below) it is left as written instead. A `translate`
+ * or `data-notrans` whose value is an expression is known only at runtime. In a `<Translate>` a
+ * value under it is marked and passed as a param too, so excluded it shows as written, and
+ * translated the core reads the marker as its placeholder and fills it from the param, which wins
+ * over the marked text. In a `<Phrase>` it is a placeholder like any other: translated, the phrase
+ * fills it; excluded, the core keys the element as one empty pair and fills the caller's params into
+ * an author's exclusion. A `<Phrase>` holding a marker of its own in its text (inside a conditional
+ * or a component too) is served as its source until a translation exists, so its other values are
+ * marked too, and passed as params; one in its translated text where no marker can stand is left
+ * as written, and the phrase gets `data-ls-unnamed`. A name a marker already carries is taken, as an
+ * explicit `%name%` is. An opt-out passed through a spread is not seen. Where no marker element
+ * can stand — inside MathML and SVG an HTML `<span>` draws nothing, and `<textarea>`, `<title>` and
+ * `<option>` hold text only — a value in such a subtree is left as written, and a `<Translate>`,
+ * which would store it, gets `data-ls-unnamed` and registers nothing (VAR-7); a `<Phrase>` keys the
+ * subtree as one empty pair. `<script>`, `<style>` and `<plaintext>` hold raw text, which a block
+ * stores as written and a phrase keys as one empty pair: a value there is left as written, and a `<Translate>`
+ * holding one gets `data-ls-unnamed`.
+ *
+ *   <Translate>Signed in as <DontTranslate>{user.email}</DontTranslate></Translate>
+ *     → <Translate>Signed in as <DontTranslate><span data-ls-param="email">{user.email}</span></DontTranslate></Translate>
+ *
+ * A block's tokens begin with each element's attributes a translator reads (TOK-3: the core's
+ * `TRANSLATABLE_ATTRIBUTES`, and the value of a button or a submit or button input), so in a
+ * `<Translate>` a value in one is a placeholder too. A value only in attributes' text travels as the
+ * string JavaScript writes there; one that is the whole attribute, or also in the content, travels
+ * as given and fills its placeholder as a value fills text, and one React renders as nodes (a list,
+ * an object) is put back as a whole prop and fills an attribute's text as JavaScript writes it into a
+ * string (`withNodeParams`). On an element whose opt-out or input type is
+ * an expression, which only the page decides, the value is left as written and the `<Translate>`
+ * gets `data-ls-unnamed`. A `<Phrase>` keys none of its elements' attributes, so they are left as
+ * written there.
+ *
+ *   <Translate><img alt={`Photo of ${user.name}`} /> Hi {user.name}</Translate>
+ *     → <Translate params={{ name: user.name }}><img alt={"Photo of %name%"} /> Hi %name%</Translate>
+ *
+ * The core reads `%name%` left to right, so where the text before a value ends in a `%` and a name
+ * it has not closed (`%s{x}`), the placeholder's own `%` would close it; there the placeholder is
+ * written in the stored form, `{name}`, which the core reads the same way (`%s{x}`). The text is read
+ * as the core registers it (C0 control characters dropped) and as it renders it (kept).
+ *
+ * Only `<Translate>` and `<Phrase>` imported from `langsys-js-react` are rewritten, and only the
+ * children a host element, a fragment or `<DontTranslate>` renders as text: an expression inside a
+ * nested host element (`<b>{x}</b>`) is included; one that is itself JSX or holds JSX
+ * (`items.map((i) => <li>…`), a conditional, already marked (`data-ls-param`), or sits inside
+ * another component or a nested `<Translate>` / `<Phrase>` is left alone, since React renders nodes
+ * from it rather than a value's text. `{children}` (under any TypeScript cast) that is all the
+ * text of its run in translated text (what React renders between two elements) is content to
+ * translate and is left alone; beside text, or in a subtree that is not translated, it is a value. A value whose type only the page knows, an element held in a variable, is rewritten like
+ * any other, and `<Translate>` / `<Phrase>` render it in its placeholder's place
+ * (`withNodeParams`). String, number and plain template literals (`{' '}`, `{3}`) are static text,
+ * and a fragment (`<>…</>`, React's `Fragment`) is unwrapped, as React passes its children on. A
+ * children list the transform changes reaches React as a JSX compiler hands it over from the
+ * source, each run of text one string (JSX's whitespace rule applied, a comment dropped), so the
+ * runtime never takes a unit's own text for a value split from it (VAR-7); this holds in the JSX
+ * compiler's own Babel pass and when the output is compiled again. `t()` calls are rewritten where
+ * `t` is the binding a `useT()` call made (and `<Translate>` / `<Phrase>` matched by their import's
+ * binding), so another function named `t` is left alone. A `+` chain joins as JavaScript joins it:
+ * a sum before the first string, or in parentheses, is one value. A key built in the call (its own
+ * text has no space: `errors.${code}`, `status_${status}`) is left as it is, since legacy-key mode
+ * looks it up as built. A name the developer wrote (`%name%` anywhere in a unit, a key of a params
+ * literal, `{name}` in a `t()` text whose params the build cannot read into: a variable, a spread)
+ * is never given to a value. Names follow VAR-2 (`./naming`); an expression
+ * no name can be derived from is named `value`, `value_2`, … and reported in
+ * `file.metadata.langsys.warnings`, which the Vite plugin and the Next loader surface as build
+ * warnings.
+ */
+
+interface LangsysTransformMetadata {
+    /** One entry per unnameable expression: where it is, and the name it was given. */
+    warnings: Array<{
+        line: number | null;
+        column: number | null;
+        source: string;
+        name: string;
+    }>;
+    /** How many units were rewritten. */
+    rewritten: number;
+}
+interface State extends PluginPass {
+    targets: Set<string>;
+    /** Local names of `<Phrase>`, which keys code, notation and an author's exclusion as one empty pair. */
+    phrases: Set<string>;
+    verbatim: Set<string>;
+    /** Local names of React's `Fragment`, and of the `react` module itself (`React.Fragment`). */
+    fragments: Set<string>;
+    reactModules: Set<string>;
+    hooks: Set<string>;
+    /**
+     * The declaring identifiers of `<Translate>` / `<Phrase>` and `useT` imported from the package, and
+     * of each `t` a `useT()` call bound: a binding's identifier is the same node after another plugin
+     * in the pass crawls the scope again, where its `Binding` object is not.
+     */
+    targetBindings: Set<types.Identifier>;
+    hookBindings: Set<types.Identifier>;
+    tBindings: Set<types.Identifier>;
+    meta: LangsysTransformMetadata;
+}
+type Babel = {
+    types: typeof types;
+};
+declare function langsysPlaceholders({ types: T }: Babel): PluginObj<State>;
+
+export { type LangsysTransformMetadata, langsysPlaceholders as default };

package/dist/babel.d.ts

@@ -0,0 +1,122 @@
+import { types, PluginObj, PluginPass } from '@babel/core';
+
+/**
+ * langsys-js-react/babel — the placeholder transform (spec VAR-6), as a Babel plugin.
+ *
+ * A value interpolated into translated text becomes a named placeholder, and the value travels as
+ * its param, so one sentence registers once however many users it is shown to (VAR-1):
+ *
+ *   <Translate>Hello {user.name}</Translate>
+ *     → <Translate params={{ name: user.name }}>Hello %name%</Translate>
+ *
+ *   t(`You have ${items.length} items`)
+ *     → t('You have {items_count} items', undefined, { items_count: items.length })
+ *
+ * A subtree the core shows as written — `<DontTranslate>`, a host element with `translate="no"` or
+ * `data-notrans`, or code and notation (`<template>`, `<noscript>`, `<math>`) — is never translated:
+ * a phrase keys it as one opaque element and restores its content, and a block keeps it in its
+ * stored content. A value there therefore stays where it is, in both components, and is marked as a
+ * value (VAR-3) rather than replaced, so the page shows the value and a block's stored content holds
+ * its placeholder; where no marker can stand (below) it is left as written instead. A `translate`
+ * or `data-notrans` whose value is an expression is known only at runtime. In a `<Translate>` a
+ * value under it is marked and passed as a param too, so excluded it shows as written, and
+ * translated the core reads the marker as its placeholder and fills it from the param, which wins
+ * over the marked text. In a `<Phrase>` it is a placeholder like any other: translated, the phrase
+ * fills it; excluded, the core keys the element as one empty pair and fills the caller's params into
+ * an author's exclusion. A `<Phrase>` holding a marker of its own in its text (inside a conditional
+ * or a component too) is served as its source until a translation exists, so its other values are
+ * marked too, and passed as params; one in its translated text where no marker can stand is left
+ * as written, and the phrase gets `data-ls-unnamed`. A name a marker already carries is taken, as an
+ * explicit `%name%` is. An opt-out passed through a spread is not seen. Where no marker element
+ * can stand — inside MathML and SVG an HTML `<span>` draws nothing, and `<textarea>`, `<title>` and
+ * `<option>` hold text only — a value in such a subtree is left as written, and a `<Translate>`,
+ * which would store it, gets `data-ls-unnamed` and registers nothing (VAR-7); a `<Phrase>` keys the
+ * subtree as one empty pair. `<script>`, `<style>` and `<plaintext>` hold raw text, which a block
+ * stores as written and a phrase keys as one empty pair: a value there is left as written, and a `<Translate>`
+ * holding one gets `data-ls-unnamed`.
+ *
+ *   <Translate>Signed in as <DontTranslate>{user.email}</DontTranslate></Translate>
+ *     → <Translate>Signed in as <DontTranslate><span data-ls-param="email">{user.email}</span></DontTranslate></Translate>
+ *
+ * A block's tokens begin with each element's attributes a translator reads (TOK-3: the core's
+ * `TRANSLATABLE_ATTRIBUTES`, and the value of a button or a submit or button input), so in a
+ * `<Translate>` a value in one is a placeholder too. A value only in attributes' text travels as the
+ * string JavaScript writes there; one that is the whole attribute, or also in the content, travels
+ * as given and fills its placeholder as a value fills text, and one React renders as nodes (a list,
+ * an object) is put back as a whole prop and fills an attribute's text as JavaScript writes it into a
+ * string (`withNodeParams`). On an element whose opt-out or input type is
+ * an expression, which only the page decides, the value is left as written and the `<Translate>`
+ * gets `data-ls-unnamed`. A `<Phrase>` keys none of its elements' attributes, so they are left as
+ * written there.
+ *
+ *   <Translate><img alt={`Photo of ${user.name}`} /> Hi {user.name}</Translate>
+ *     → <Translate params={{ name: user.name }}><img alt={"Photo of %name%"} /> Hi %name%</Translate>
+ *
+ * The core reads `%name%` left to right, so where the text before a value ends in a `%` and a name
+ * it has not closed (`%s{x}`), the placeholder's own `%` would close it; there the placeholder is
+ * written in the stored form, `{name}`, which the core reads the same way (`%s{x}`). The text is read
+ * as the core registers it (C0 control characters dropped) and as it renders it (kept).
+ *
+ * Only `<Translate>` and `<Phrase>` imported from `langsys-js-react` are rewritten, and only the
+ * children a host element, a fragment or `<DontTranslate>` renders as text: an expression inside a
+ * nested host element (`<b>{x}</b>`) is included; one that is itself JSX or holds JSX
+ * (`items.map((i) => <li>…`), a conditional, already marked (`data-ls-param`), or sits inside
+ * another component or a nested `<Translate>` / `<Phrase>` is left alone, since React renders nodes
+ * from it rather than a value's text. `{children}` (under any TypeScript cast) that is all the
+ * text of its run in translated text (what React renders between two elements) is content to
+ * translate and is left alone; beside text, or in a subtree that is not translated, it is a value. A value whose type only the page knows, an element held in a variable, is rewritten like
+ * any other, and `<Translate>` / `<Phrase>` render it in its placeholder's place
+ * (`withNodeParams`). String, number and plain template literals (`{' '}`, `{3}`) are static text,
+ * and a fragment (`<>…</>`, React's `Fragment`) is unwrapped, as React passes its children on. A
+ * children list the transform changes reaches React as a JSX compiler hands it over from the
+ * source, each run of text one string (JSX's whitespace rule applied, a comment dropped), so the
+ * runtime never takes a unit's own text for a value split from it (VAR-7); this holds in the JSX
+ * compiler's own Babel pass and when the output is compiled again. `t()` calls are rewritten where
+ * `t` is the binding a `useT()` call made (and `<Translate>` / `<Phrase>` matched by their import's
+ * binding), so another function named `t` is left alone. A `+` chain joins as JavaScript joins it:
+ * a sum before the first string, or in parentheses, is one value. A key built in the call (its own
+ * text has no space: `errors.${code}`, `status_${status}`) is left as it is, since legacy-key mode
+ * looks it up as built. A name the developer wrote (`%name%` anywhere in a unit, a key of a params
+ * literal, `{name}` in a `t()` text whose params the build cannot read into: a variable, a spread)
+ * is never given to a value. Names follow VAR-2 (`./naming`); an expression
+ * no name can be derived from is named `value`, `value_2`, … and reported in
+ * `file.metadata.langsys.warnings`, which the Vite plugin and the Next loader surface as build
+ * warnings.
+ */
+
+interface LangsysTransformMetadata {
+    /** One entry per unnameable expression: where it is, and the name it was given. */
+    warnings: Array<{
+        line: number | null;
+        column: number | null;
+        source: string;
+        name: string;
+    }>;
+    /** How many units were rewritten. */
+    rewritten: number;
+}
+interface State extends PluginPass {
+    targets: Set<string>;
+    /** Local names of `<Phrase>`, which keys code, notation and an author's exclusion as one empty pair. */
+    phrases: Set<string>;
+    verbatim: Set<string>;
+    /** Local names of React's `Fragment`, and of the `react` module itself (`React.Fragment`). */
+    fragments: Set<string>;
+    reactModules: Set<string>;
+    hooks: Set<string>;
+    /**
+     * The declaring identifiers of `<Translate>` / `<Phrase>` and `useT` imported from the package, and
+     * of each `t` a `useT()` call bound: a binding's identifier is the same node after another plugin
+     * in the pass crawls the scope again, where its `Binding` object is not.
+     */
+    targetBindings: Set<types.Identifier>;
+    hookBindings: Set<types.Identifier>;
+    tBindings: Set<types.Identifier>;
+    meta: LangsysTransformMetadata;
+}
+type Babel = {
+    types: typeof types;
+};
+declare function langsysPlaceholders({ types: T }: Babel): PluginObj<State>;
+
+export { type LangsysTransformMetadata, langsysPlaceholders as default };