svelte-component-i18n 0.0.1 → 0.1.0

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Lukas Dietrich
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -1,58 +1,116 @@
-# Svelte library
+# svelte-component-i18n
 
-Everything you need to build a Svelte library, powered by [`sv`](https://npmjs.com/package/sv).
+A lightweight internationalization library for Svelte.
+It acts as a thin wrapper around native browser APIs, prioritizing type safety and component-level
+translation management.
 
-Read more about creating a library [in the docs](https://svelte.dev/docs/kit/packaging).
+## Usage Examples
 
-## Creating a project
+The following examples are simplified. Ideally you construct one `Translator` and reuse it in every
+component, only defining translations there.
 
-If you're seeing this, you've probably already done this step. Congrats!
+### Language Detection
 
-```sh
-# create a new project in the current directory
-npx sv create
+Detecting the user's preferred language using `navigator.languages` or a previously selected language
+from the `localStorage`.
 
-# create a new project in my-app
-npx sv create my-app
+```typescript
+import { fromLocalStorage, fromNavigator, toLocalStorage, Translator } from 'svelte-component-i18n';
+
+const localStorageKey = 'my-app-language';
+
+const translator = new Translator({
+    supportedLanguages: ['en', 'de'],
+    fallbackLanguage: 'en',
+    languageStrategies: [fromLocalStorage(localStorageKey), fromNavigator()],
+    languageHooks: [toLocalStorage(localStorageKey)],
+});
 ```
 
-## Developing
+### Language Selection
 
-Once you've created a project and installed dependencies with `npm install` (or `pnpm install` or `yarn`), start a development server:
+Managing and updating the current active locale store.
 
-```sh
-npm run dev
+```svelte
+<script lang="ts">
+  import { Translator } from 'svelte-component-i18n';
 
-# or start the server and open the app in a new browser tab
-npm run dev -- --open
+  const translator = new Translator({
+    supportedLanguages: ['en', 'de'],
+    fallbackLanguage: 'en',
+  });
+</script>
+
+<select bind:value={translator.currentLanguage}>
+  {#each translator.supportedLanguages as language (language)}
+    <option value={language}>{language}</option>
+  {/each}
+</select>
 ```
 
-Everything inside `src/lib` is part of your library, everything inside `src/routes` can be used as a showcase or preview app.
+### Simple Translations
 
-## Building
+Basic key-value mapping for static text.
 
-To build your library:
+```svelte
+<script lang="ts">
+import { translator } from '$lib/my-globally-defined-translator';
 
-```sh
-npm pack
-```
+const { t } = translator.define({
+    simple: {
+        en: 'Simple',
+        de: 'Einfach',
+    },
+});
+</script>
 
-To create a production version of your showcase app:
-
-```sh
-npm run build
+{t('simple')}
 ```
 
-You can preview the production build with `npm run preview`.
+### Pluralization
+
+Using `Intl.PluralRules` logic to handle count-based text variations.
+
+```svelte
+<script lang="ts">
+import { translator } from '$lib/my-globally-defined-translator';
+
+const { p } = translator.define({
+    pluralized: {
+        en: {
+            one: 'One thing',
+            other: 'Many things',
+        },
+        de: {
+            one: 'Ein Ding',
+            other: 'Viele Dinge',
+        },
+    },
+});
+</script>
+
+{p('pluralized', 1)}
+{p('pluralized', 42)}
+```
 
-> To deploy your app, you may need to install an [adapter](https://svelte.dev/docs/kit/adapters) for your target environment.
+### Interpolation
 
-## Publishing
+Instead of defining static structures you can also define functions, which return the same structures.
+Template literals can be used to interpolate text.
 
-Go into the `package.json` and give your package the desired name through the `"name"` option. Also consider adding a `"license"` field and point it to a `LICENSE` file which you can create from a template (one popular option is the [MIT license](https://opensource.org/license/mit/)).
+```svelte
+<script lang="ts">
+import { translator } from '$lib/my-globally-defined-translator';
 
-To publish your library to [npm](https://www.npmjs.com):
+const { t } = translator.define({
+    parameterized: (name: string) => ({
+        en: `Hello ${name}`,
+        de: `Hallo ${name}`,
+    }),
+});
+</script>
 
-```sh
-npm publish
+{t('parameterized', 'Svelte')}
 ```
+
+[^1]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/PluralRules

package/dist/detect.d.ts

@@ -0,0 +1,5 @@
+export type LanguageStrategy<Languages extends string> = (supportedLanguages: Languages[]) => Languages | undefined;
+export declare function fromNavigator<Languages extends string>(): LanguageStrategy<Languages>;
+export declare function fromLocalStorage<Languages extends string>(key: string): LanguageStrategy<Languages>;
+export type LanguageHook<Languages extends string> = (language: Languages) => unknown;
+export declare function toLocalStorage<Languages extends string>(key: string): LanguageHook<Languages>;

package/dist/detect.js

@@ -0,0 +1,37 @@
+import { browser } from '$app/environment';
+export function fromNavigator() {
+    return (supportedLanguages) => {
+        if (!browser) {
+            return;
+        }
+        for (const navigatorLanguage of navigator.languages) {
+            const language = navigatorLanguage;
+            if (supportedLanguages.includes(language)) {
+                return language;
+            }
+        }
+    };
+}
+export function fromLocalStorage(key) {
+    return (supportedLanguages) => {
+        if (!browser) {
+            return;
+        }
+        const localStorageLanguage = localStorage.getItem(key);
+        if (typeof localStorageLanguage !== 'string') {
+            return;
+        }
+        const language = localStorageLanguage;
+        if (supportedLanguages.includes(language)) {
+            return language;
+        }
+    };
+}
+export function toLocalStorage(key) {
+    return (language) => {
+        if (!browser) {
+            return;
+        }
+        localStorage.setItem(key, language);
+    };
+}

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 export { Translator } from './translator.svelte.ts';
 export { type Dictionary, type Texts } from './dictionary.ts';
+export { type LanguageStrategy, type LanguageHook, fromNavigator, fromLocalStorage, toLocalStorage, } from './detect.ts';

package/dist/index.js

@@ -1,2 +1,3 @@
 export { Translator } from "./translator.svelte.js";
 export {} from "./dictionary.js";
+export { fromNavigator, fromLocalStorage, toLocalStorage, } from "./detect.js";

package/dist/translator.svelte.d.ts

@@ -1,9 +1,17 @@
 import { Dictionary, type Texts } from './dictionary.ts';
+import type { LanguageHook, LanguageStrategy } from './detect.ts';
+type MustStringUnion<T extends string> = string extends T ? never : T;
 export declare class Translator<Languages extends string, Fallback extends Languages> {
-    readonly languages: Languages[];
-    readonly fallback: Fallback;
+    readonly supportedLanguages: Languages[];
+    readonly fallbackLanguage: Fallback;
     currentLanguage: Languages;
     private readonly locale;
-    constructor(languages: Languages[], fallback: Fallback);
+    constructor({ supportedLanguages, fallbackLanguage, languageStrategies, languageHooks, }: {
+        supportedLanguages: MustStringUnion<Languages>[];
+        fallbackLanguage: Fallback;
+        languageStrategies?: LanguageStrategy<Languages>[];
+        languageHooks?: LanguageHook<Languages>[];
+    });
     define<T>(texts: Texts<Languages, Fallback, T>): Dictionary<Languages, Fallback, T>;
 }
+export {};

package/dist/translator.svelte.js

@@ -1,19 +1,25 @@
 import { Dictionary } from "./dictionary.js";
 export class Translator {
-    languages;
-    fallback;
+    supportedLanguages;
+    fallbackLanguage;
     currentLanguage;
     locale;
-    constructor(languages, fallback) {
-        this.languages = languages;
-        this.fallback = fallback;
-        checkSupportedLanguages(languages);
-        this.currentLanguage = $state(fallback);
+    constructor({ supportedLanguages, fallbackLanguage, languageStrategies = [], languageHooks = [], }) {
+        checkSupportedLanguages(supportedLanguages);
+        this.supportedLanguages = supportedLanguages;
+        this.fallbackLanguage = fallbackLanguage;
+        const initialLanguage = determineInitialLanguage(languageStrategies, supportedLanguages, fallbackLanguage);
+        this.currentLanguage = $state(initialLanguage);
         this.locale = $derived({
             language: this.currentLanguage,
-            fallback: this.fallback,
+            fallback: this.fallbackLanguage,
             pluralRules: new Intl.PluralRules(this.currentLanguage),
         });
+        $effect(() => {
+            for (const hook of languageHooks) {
+                hook(this.currentLanguage);
+            }
+        });
     }
     define(texts) {
         return new Dictionary(() => this.locale, texts);
@@ -26,3 +32,12 @@ function checkSupportedLanguages(languages) {
         throw new Error(`Unsupported languages: ${unsupportedLanguages}`);
     }
 }
+function determineInitialLanguage(strategies, languages, fallback) {
+    for (const strategy of strategies) {
+        const language = strategy(languages);
+        if (language !== undefined) {
+            return language;
+        }
+    }
+    return fallback;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-component-i18n",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "scripts": {
     "dev": "vite dev",
     "build": "vite build && npm run prepack",
@@ -35,17 +35,17 @@
     "svelte": "^5.0.0"
   },
   "devDependencies": {
-    "@eslint/compat": "^1.4.0",
+    "@eslint/compat": "^2.0.0",
     "@eslint/js": "^9.39.1",
     "@sveltejs/adapter-auto": "^7.0.0",
     "@sveltejs/kit": "^2.49.1",
     "@sveltejs/package": "^2.5.7",
     "@sveltejs/vite-plugin-svelte": "^6.2.1",
-    "@types/node": "^22",
+    "@types/node": "^25.0.3",
     "eslint": "^9.39.1",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-svelte": "^3.13.1",
-    "globals": "^16.5.0",
+    "globals": "^17.0.0",
     "prettier": "^3.7.4",
     "prettier-plugin-svelte": "^3.4.0",
     "publint": "^0.3.15",