@firsthandjs/i18n 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Firsthand contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,42 @@
+# @firsthandjs/i18n
+
+Makes a translation function reactive: switch the language and every translated
+part on the page updates, without a re-render, a provider or a context.
+
+**Documentation:** [guide](https://github.com/firsthandjs/firsthand/blob/main/docs/guide/12-internationalisation.md) · [API reference](https://github.com/firsthandjs/firsthand/blob/main/docs/reference/i18n.md) · [all docs](https://github.com/firsthandjs/firsthand/blob/main/docs/README.md)
+
+```
+npm install @firsthandjs/i18n
+```
+
+0.38 kB gzip. It depends on `@firsthandjs/core` and on nothing else — not even
+on i18next, whose shape it describes structurally rather than importing.
+
+```ts
+import i18next from 'i18next';
+import { fromI18next } from '@firsthandjs/i18n';
+
+await i18next.init({ lng: 'en', resources });
+export const { t, language } = fromI18next(i18next);
+```
+
+```tsx
+<h1>{t('greeting', { name: 'Ada' })}</h1>
+```
+
+That `h1` re-reads when the language changes, and so does every other part that
+called `t` — and nothing else does.
+
+i18next, FormatJS, Lingui and Polyglot all work in this framework already; they
+are plain JavaScript. What none of them can do is tell the reactive graph that
+the answer changed, so a label rendered before the switch keeps its old text.
+This package is the connection and nothing more: there is no dictionary here,
+no plural rules and no date formatting, because the libraries that do those
+things are good at them.
+
+`translator()` adapts anything with a `t`, a current language and a way to
+subscribe. `fromI18next()` is that adapter for i18next, listening on the
+instance _and_ on its resource store — a namespace that arrives late, or a key
+added at runtime, changes the answer as surely as a language switch does.
+
+MIT licensed.

package/dist/index.d.ts

@@ -0,0 +1,98 @@
+/**
+ * `@firsthandjs/i18n` — makes a translation function reactive.
+ *
+ * i18next, FormatJS, Lingui and Polyglot all work here already: they are plain
+ * JavaScript, and nothing about this framework stops you calling `t('greeting')`.
+ * What none of them do is tell the *graph* that the answer changed, so a label
+ * rendered before the language switch keeps its old text.
+ *
+ * ```tsx
+ * import i18next from 'i18next';
+ * import { fromI18next } from '@firsthandjs/i18n';
+ *
+ * await i18next.init({ lng: 'en', resources });
+ * export const { t, language } = fromI18next(i18next);
+ *
+ * // and then, in a component:
+ * <h1>{t('greeting', { name: 'Ada' })}</h1>   // re-reads on a language change
+ * ```
+ *
+ * The whole package is a version signal and a wrapper that reads it. There is
+ * no dictionary here, no plural rules, no date formatting and no intention of
+ * ever having any: the libraries that do that are good, and this is the eleven
+ * lines that connect them.
+ */
+import { type Dispose, type ReadonlyCell } from '@firsthandjs/core';
+/** A translation function, whatever shape the library gave it. */
+type Translate = (...args: never[]) => unknown;
+/** What a localisation library has to offer to be made reactive. */
+export interface Source<T extends Translate> {
+    /** The library's own `t`, untouched — its types are the ones you keep. */
+    translate: T;
+    /** The language in effect right now, read when something asks. */
+    language: () => string;
+    /**
+     * Calls `changed` whenever a translation could answer differently, and
+     * returns the way to stop listening.
+     *
+     * "Could answer differently" is wider than "the language changed": a backend
+     * that loads a namespace late changes the answer too, and forgetting that is
+     * why translations sometimes appear as their keys for a moment and then
+     * never recover.
+     */
+    subscribe: (changed: () => void) => Dispose;
+}
+/** A reactive translation function, and the language it is reading. */
+export interface Translator<T extends Translate> {
+    /** The same function, with the same types, that now re-runs when it should. */
+    t: T;
+    /** The current language, as a cell: read it in a part and it stays current. */
+    language: ReadonlyCell<string>;
+    /** Stops listening. Registered with the enclosing scope, if there is one. */
+    dispose: Dispose;
+}
+/**
+ * Wraps any translation function so that reading it subscribes.
+ *
+ * The wrapper reads a version signal and then calls through. That is the whole
+ * mechanism: a part that renders a translation has read the signal, so a
+ * language change re-runs exactly that part and nothing else — no re-render,
+ * no provider, no context.
+ *
+ * If called inside a component or a root, the subscription is disposed with
+ * that scope. At module level — which is where an application usually sets up
+ * its translations — nothing owns it, so it lives as long as the page and
+ * `dispose` is there for the cases that need it.
+ */
+export declare function translator<T extends Translate>(source: Source<T>): Translator<T>;
+/**
+ * The shape this package needs from i18next.
+ *
+ * Declared structurally rather than imported, so the package has no dependency
+ * on i18next, no opinion about its version, and works with anything that looks
+ * like it — `createInstance()`, a mock in a test, or a fork.
+ */
+export interface I18nextLike<T extends Translate> {
+    t: T;
+    language: string;
+    on(event: string, handler: () => void): void;
+    off(event: string, handler: () => void): void;
+    /**
+     * The resource store, if this instance has one.
+     *
+     * i18next announces a *language* change on the instance and a *resource*
+     * change on the store. Listening only to the instance is the mistake that
+     * makes `addResource` look like it did nothing — it was found by testing
+     * against the real library rather than against something shaped like it.
+     */
+    store?: Emitter;
+}
+/** The part of an event emitter this package uses. */
+export interface Emitter {
+    on(event: string, handler: () => void): void;
+    off(event: string, handler: () => void): void;
+}
+/** Connects an i18next instance. See {@link translator} for what it does. */
+export declare function fromI18next<T extends Translate>(instance: I18nextLike<T>): Translator<T>;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,EAKL,KAAK,OAAO,EACZ,KAAK,YAAY,EAClB,MAAM,mBAAmB,CAAC;AAE3B,kEAAkE;AAClE,KAAK,SAAS,GAAG,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,CAAC;AAE/C,oEAAoE;AACpE,MAAM,WAAW,MAAM,CAAC,CAAC,SAAS,SAAS;IACzC,0EAA0E;IAC1E,SAAS,EAAE,CAAC,CAAC;IACb,kEAAkE;IAClE,QAAQ,EAAE,MAAM,MAAM,CAAC;IACvB;;;;;;;;OAQG;IACH,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,IAAI,KAAK,OAAO,CAAC;CAC7C;AAED,uEAAuE;AACvE,MAAM,WAAW,UAAU,CAAC,CAAC,SAAS,SAAS;IAC7C,+EAA+E;IAC/E,CAAC,EAAE,CAAC,CAAC;IACL,+EAA+E;IAC/E,QAAQ,EAAE,YAAY,CAAC,MAAM,CAAC,CAAC;IAC/B,6EAA6E;IAC7E,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CA8BhF;AAED;;;;;;GAMG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC,SAAS,SAAS;IAC9C,CAAC,EAAE,CAAC,CAAC;IACL,QAAQ,EAAE,MAAM,CAAC;IACjB,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAC7C,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAC9C;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,sDAAsD;AACtD,MAAM,WAAW,OAAO;IACtB,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAC7C,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;CAC/C;AAcD,6EAA6E;AAC7E,wBAAgB,WAAW,CAAC,CAAC,SAAS,SAAS,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CA4BxF"}

package/dist/index.js

@@ -0,0 +1 @@
+import{batch as f,getOwner as g,onCleanup as T,signal as a}from"@firsthandjs/core";function u(e){let n=a(0),o=a(e.language()),t=e.subscribe(()=>{f(()=>{o.value=e.language(),n.value++})}),i=((...d)=>(n.value,e.translate(...d))),r=()=>{t()};return g()!==null&&T(r),{t:i,language:o,dispose:r}}var s=["languageChanged","loaded"],l=["added","removed"];function c(e){return u({translate:((...n)=>e.t(...n)),language:()=>e.language,subscribe:n=>{let o=e.store;for(let t of s)e.on(t,n);if(o!==void 0)for(let t of l)o.on(t,n);return()=>{for(let t of s)e.off(t,n);if(o!==void 0)for(let t of l)o.off(t,n)}}})}export{c as fromI18next,u as translator};

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@firsthandjs/i18n",
+  "version": "0.4.0",
+  "description": "Makes i18next (or any translation function) reactive in Firsthand.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "main": "./dist/index.js",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@firsthandjs/core": "0.4.0"
+  },
+  "engines": {
+    "node": ">=20.11.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/firsthandjs/firsthand.git",
+    "directory": "packages/i18n"
+  },
+  "bugs": {
+    "url": "https://github.com/firsthandjs/firsthand/issues"
+  },
+  "homepage": "https://github.com/firsthandjs/firsthand#readme",
+  "keywords": [
+    "firsthand",
+    "i18n",
+    "i18next",
+    "localisation",
+    "translation",
+    "reactive"
+  ]
+}