@vireocodedev/localization 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vireocodedev
+
+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,179 @@
+# @vireocodedev/localization
+
+Framework-free localization resources and tooling shared by the Starter
+packages. It is the single owner of the `platform`, `queryengine`, and `history`
+i18next namespaces.
+
+The package owns translation resources, namespace constants, resource
+factories, imperative registration, deep-merge utilities, and locale-neutral
+number formatting. It deliberately does not own React hooks, providers,
+i18next initialization, locale detection, persistence, or application locale
+policy.
+
+The package has no React dependency and is safe to load in Node and Web Workers.
+React consumers import namespace hooks from
+`@vireocodedev/ui/react-i18next`.
+
+## Install
+
+```bash
+npm install @vireocodedev/localization i18next
+```
+
+The package is published publicly on npm; installation requires no registry
+authentication.
+
+`i18next` is the only peer dependency. The package runs against the consuming
+application's instance and never bundles its own copy.
+
+TypeScript declarations are verified from the packed artifact with TypeScript
+6, `moduleResolution: "Bundler"`, and `skipLibCheck: false`. Relative source
+maps with embedded source content are published intentionally for debugging.
+
+## Primary workflow
+
+Create every Starter namespace for the locales your app supports, add the
+application's own namespace, then pass the combined resources to an app-owned
+i18next instance:
+
+```ts
+import { createStarterResources } from "@vireocodedev/localization";
+import { createInstance } from "i18next";
+
+const locales = ["en", "hr"] as const;
+const starterResources = createStarterResources({ locales });
+const resources = {
+  en: { app: { home: { title: "Overview" } }, ...starterResources.en },
+  hr: { app: { home: { title: "Pregled" } }, ...starterResources.hr },
+};
+
+const i18next = createInstance();
+await i18next.init({
+  defaultNS: "app",
+  initAsync: false,
+  lng: "hr",
+  fallbackLng: "en",
+  resources,
+});
+```
+
+Locales not shipped by Starter are seeded from English by default. Partial
+overrides are deeply merged, so untranslated keys retain the seed value. Set
+`seedFrom: "hr"` to use Croatian as the seed instead.
+
+Every generated locale owns an isolated resource tree. Mutating one result does
+not mutate the shipped base resources or another locale.
+
+## Registering resources after initialization
+
+Use `registerStarterResources` when an initialized instance needs the resources
+later in its lifecycle:
+
+```ts
+import { registerStarterResources } from "@vireocodedev/localization";
+
+registerStarterResources(i18next, {
+  locales: ["en", "hr"],
+});
+```
+
+The function registers every Starter namespace. Per-namespace factories remain
+available when a consumer intentionally needs only one namespace.
+
+## React consumption
+
+React adapters belong to Starter UI. In a React application, install
+`initReactI18next` on the same app-owned instance **before its single call to
+`init`**, then expose that instance through `I18nextProvider`; Starter UI's
+hooks read that provider:
+
+```tsx
+import type { PropsWithChildren } from "react";
+import { I18nextProvider, initReactI18next } from "react-i18next";
+import { usePlatformTranslation } from "@vireocodedev/ui/react-i18next";
+
+const reactI18next = createInstance();
+void reactI18next.use(initReactI18next).init({
+  defaultNS: "app",
+  fallbackLng: "en",
+  initAsync: false,
+  lng: "en",
+  resources,
+});
+
+export function AppLocalizationProvider({ children }: PropsWithChildren) {
+  return <I18nextProvider i18n={reactI18next}>{children}</I18nextProvider>;
+}
+
+export function SaveButton() {
+  const { t } = usePlatformTranslation();
+  return <button>{t("common.save")}</button>;
+}
+```
+
+`useQueryEngineTranslation` and `useHistoryTranslation` are available from the
+same UI subpath. This package itself remains usable without React.
+
+## Type safety
+
+Augment i18next with the exported namespace resource types for strict keys and
+autocomplete:
+
+```ts
+import type { HistoryResources, PlatformResources, QueryEngineResources } from "@vireocodedev/localization";
+
+declare module "i18next" {
+  interface CustomTypeOptions {
+    resources: {
+      platform: PlatformResources;
+      queryengine: QueryEngineResources;
+      history: HistoryResources;
+    };
+  }
+}
+```
+
+## Public API
+
+| Export                                                                      | Purpose                                                             |
+| --------------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| `createStarterResources`                                                    | Build every Starter namespace for requested locales.                |
+| `registerStarterResources`                                                  | Register every namespace on a caller-owned i18next instance.        |
+| `createPlatformResources`                                                   | Build only the `platform` namespace.                                |
+| `createQueryEngineResources`                                                | Build only the `queryengine` namespace.                             |
+| `createHistoryResources`                                                    | Build only the `history` namespace.                                 |
+| `STARTER_TRANSLATION_NAMESPACES`, `STARTER_BASE_LOCALES`                    | Shipped namespace and locale contracts.                             |
+| `*_TRANSLATION_NAMESPACE`, `*_BASE_LOCALES`                                 | Per-namespace constants.                                            |
+| `platformBaseResources`, `queryEngineBaseResources`, `historyBaseResources` | Shipped resource maps.                                              |
+| `createNamespaceResources`                                                  | Build a complete custom namespace from shipped seeds and overrides. |
+| `deepMerge`                                                                 | Immutable, prototype-safe merge used by resource factories.         |
+| `formatIntlNumber`                                                          | Format a number with caller-owned locale and fallback policy.       |
+| Resource/configuration utility types                                        | Type namespace shapes, overrides, and custom factories.             |
+
+## Failure and versioning policy
+
+Resource factories reject blank namespaces, empty locale sets, blank or
+duplicate locale identifiers, missing seed locales, and overrides targeting a
+locale that was not requested. Prototype-mutating override keys are ignored.
+
+Translation keys and base locales are versioned contracts:
+
+- adding a key, namespace, or locale is a minor release;
+- renaming/removing a key or dropping a base locale is breaking;
+- changing a shipped translation value is reviewed as user-visible behavior.
+
+Explicit contract tests guard namespace keys and locale parity.
+
+## Live documentation
+
+The shared Vireo Starter Storybook contains the package's executable primary
+workflow, late-registration path, custom-namespace toolkit, number formatting,
+and failure semantics. Every displayed example imports this package through its
+published entry point, is typechecked with the package, and executes from the
+same source shown to readers.
+
+## Scripts
+
+- `npm run build` — build the ESM runtime and bundled declarations.
+- `npm run typecheck` — typecheck source and tests without emitting.
+- `npm run test` — run behavior, workflow, resource-contract, and architecture tests.

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@vireocodedev/localization",
+  "version": "0.2.0",
+  "description": "Foundation i18n toolkit and shared platform translations for the vireocodedev starter product.",
+  "type": "module",
+  "sideEffects": false,
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vireocodedev/starter.git",
+    "directory": "packages/localization"
+  },
+  "keywords": [
+    "i18n",
+    "i18next",
+    "localization",
+    "starter"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "dev": "vite build --watch --mode watch",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "peerDependencies": {
+    "i18next": ">=26 <27"
+  },
+  "devDependencies": {
+    "i18next": "^26.4.0",
+    "typescript": "npm:@typescript/typescript6@^6.0.2",
+    "vite": "^8.2.2",
+    "vite-plugin-dts": "^5.0.3",
+    "vitest": "^4.1.11"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "registry": "https://registry.npmjs.org"
+  }
+}