svelte-component-i18n 0.1.0 → 0.1.3

package/README.md

@@ -1,18 +1,74 @@
 # svelte-component-i18n
 
 A lightweight internationalization library for Svelte.
+
 It acts as a thin wrapper around native browser APIs, prioritizing type safety and component-level
 translation management.
 
-## Usage Examples
+## Installation
+
+```bash
+npm i -S svelte-component-i18n
+```
+
+## Usage
 
-The following examples are simplified. Ideally you construct one `Translator` and reuse it in every
-component, only defining translations there.
+This library consists of two parts:
+
+1. `Translator` keeps track of the current locale and propagates changes to all components.
+2. `Dictionary` is a component level record of translations.
+
+First should create just one global `Translator` instance and reuse it in every component.
+
+```typescript
+// src/lib/i18n.ts
+
+import { Translator } from 'svelte-component-i18n';
+
+export const translator = new Translator({
+  // All languages you want to support.
+  supportedLanguages: ['en', 'de'],
+  // The fallback language is the only one, where translations are required to be defined.
+  // If a translation for a given language is missing, the fallback language is used instead.
+  fallbackLanguage: 'en',
+});
+```
+
+Next you should define a `Dictionary` in your components.
+
+```svelte
+<!--
+    You can define translations in a `module`-Block, as it is shared across instances of the
+    same component.
+-->
+<script lang="ts" module>
+  import { translator } from '$lib/i18n';
+
+  // You can destruct the dictionary into the required translation functions.
+  //   - `translate` and `t`: Translate a key
+  //   - `pluralize` and `p`: Translate a key taking pluralization into account
+  const { t } = translator.define({
+    myFirstTranslation: {
+      en: 'My first translation',
+      de: 'Meine erste Übersetzung',
+    },
+  });
+</script>
+
+<!--
+    The keys and parameters are type-checked.
+    If the key is not defined, the component will not compile.
+-->
+<p>{t('myFirstTranslation')}</p>
+```
 
 ### Language Detection
 
-Detecting the user's preferred language using `navigator.languages` or a previously selected language
-from the `localStorage`.
+Detecting the user's preferred language using `navigator.languages` or a previously selected
+language from the `localStorage`.
+
+Browser globals are not defined when using server-side rendering in SvelteKit.
+The provided strategies and hooks skip execution, when `navigator` or `localStorage` are missing.
 
 ```typescript
 import { fromLocalStorage, fromNavigator, toLocalStorage, Translator } from 'svelte-component-i18n';
@@ -20,25 +76,22 @@ import { fromLocalStorage, fromNavigator, toLocalStorage, Translator } from 'sve
 const localStorageKey = 'my-app-language';
 
 const translator = new Translator({
-    supportedLanguages: ['en', 'de'],
-    fallbackLanguage: 'en',
-    languageStrategies: [fromLocalStorage(localStorageKey), fromNavigator()],
-    languageHooks: [toLocalStorage(localStorageKey)],
+  supportedLanguages: ['en', 'de'],
+  fallbackLanguage: 'en',
+  languageStrategies: [fromLocalStorage(localStorageKey), fromNavigator()],
+  languageHooks: [toLocalStorage(localStorageKey)],
 });
 ```
 
 ### Language Selection
 
-Managing and updating the current active locale store.
+The `Translator` exposes both the `currentLanguage` and the initially provided `supportedLanguages`.
+You can use both to create a language selector.
+The `currentLanguage` is a rune and will automatically propagate changes to all components.
 
 ```svelte
-<script lang="ts">
-  import { Translator } from 'svelte-component-i18n';
-
-  const translator = new Translator({
-    supportedLanguages: ['en', 'de'],
-    fallbackLanguage: 'en',
-  });
+<script lang="ts" module>
+  import { translator } from '$lib/i18n';
 </script>
 
 <select bind:value={translator.currentLanguage}>
@@ -53,15 +106,15 @@ Managing and updating the current active locale store.
 Basic key-value mapping for static text.
 
 ```svelte
-<script lang="ts">
-import { translator } from '$lib/my-globally-defined-translator';
+<script lang="ts" module>
+  import { translator } from '$lib/i18n';
 
-const { t } = translator.define({
+  const { t } = translator.define({
     simple: {
-        en: 'Simple',
-        de: 'Einfach',
+      en: 'Simple',
+      de: 'Einfach',
     },
-});
+  });
 </script>
 
 {t('simple')}
@@ -69,24 +122,24 @@ const { t } = translator.define({
 
 ### Pluralization
 
-Using `Intl.PluralRules` logic to handle count-based text variations.
+Using `Intl.PluralRules`[^1] logic to handle count-based text variations.
 
 ```svelte
-<script lang="ts">
-import { translator } from '$lib/my-globally-defined-translator';
+<script lang="ts" module>
+  import { translator } from '$lib/i18n';
 
-const { p } = translator.define({
+  const { p } = translator.define({
     pluralized: {
-        en: {
-            one: 'One thing',
-            other: 'Many things',
-        },
-        de: {
-            one: 'Ein Ding',
-            other: 'Viele Dinge',
-        },
+      en: {
+        one: 'One thing',
+        other: 'Many things',
+      },
+      de: {
+        one: 'Ein Ding',
+        other: 'Viele Dinge',
+      },
     },
-});
+  });
 </script>
 
 {p('pluralized', 1)}
@@ -99,15 +152,15 @@ Instead of defining static structures you can also define functions, which retur
 Template literals can be used to interpolate text.
 
 ```svelte
-<script lang="ts">
-import { translator } from '$lib/my-globally-defined-translator';
+<script lang="ts" module>
+  import { translator } from '$lib/i18n';
 
-const { t } = translator.define({
+  const { t } = translator.define({
     parameterized: (name: string) => ({
-        en: `Hello ${name}`,
-        de: `Hallo ${name}`,
+      en: `Hello ${name}`,
+      de: `Hallo ${name}`,
     }),
-});
+  });
 </script>
 
 {t('parameterized', 'Svelte')}

package/dist/detect.d.ts

@@ -1,5 +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 declare function fromNavigator<Languages extends string>(navigator?: typeof globalThis.navigator): LanguageStrategy<Languages>;
+export declare function fromLocalStorage<Languages extends string>(key: string, localStorage?: Storage): LanguageStrategy<Languages>;
 export type LanguageHook<Languages extends string> = (language: Languages) => unknown;
-export declare function toLocalStorage<Languages extends string>(key: string): LanguageHook<Languages>;
+export declare function toLocalStorage<Languages extends string>(key: string, localStorage?: Storage): LanguageHook<Languages>;

package/dist/detect.js

@@ -1,7 +1,6 @@
-import { browser } from '$app/environment';
-export function fromNavigator() {
+export function fromNavigator(navigator = globalThis.navigator) {
     return (supportedLanguages) => {
-        if (!browser) {
+        if (!navigator) {
             return;
         }
         for (const navigatorLanguage of navigator.languages) {
@@ -12,9 +11,9 @@ export function fromNavigator() {
         }
     };
 }
-export function fromLocalStorage(key) {
+export function fromLocalStorage(key, localStorage = globalThis.localStorage) {
     return (supportedLanguages) => {
-        if (!browser) {
+        if (!localStorage) {
             return;
         }
         const localStorageLanguage = localStorage.getItem(key);
@@ -27,9 +26,9 @@ export function fromLocalStorage(key) {
         }
     };
 }
-export function toLocalStorage(key) {
+export function toLocalStorage(key, localStorage = globalThis.localStorage) {
     return (language) => {
-        if (!browser) {
+        if (!localStorage) {
             return;
         }
         localStorage.setItem(key, language);

package/dist/translator.svelte.d.ts

@@ -2,16 +2,19 @@ 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> {
+    #private;
     readonly supportedLanguages: Languages[];
     readonly fallbackLanguage: Fallback;
-    currentLanguage: Languages;
     private readonly locale;
+    private readonly languageHooks;
     constructor({ supportedLanguages, fallbackLanguage, languageStrategies, languageHooks, }: {
         supportedLanguages: MustStringUnion<Languages>[];
         fallbackLanguage: Fallback;
         languageStrategies?: LanguageStrategy<Languages>[];
         languageHooks?: LanguageHook<Languages>[];
     });
+    get currentLanguage(): Languages;
+    set currentLanguage(language: Languages);
     define<T>(texts: Texts<Languages, Fallback, T>): Dictionary<Languages, Fallback, T>;
 }
 export {};

package/dist/translator.svelte.js

@@ -2,24 +2,30 @@ import { Dictionary } from "./dictionary.js";
 export class Translator {
     supportedLanguages;
     fallbackLanguage;
-    currentLanguage;
+    #currentLanguage;
     locale;
+    languageHooks;
     constructor({ supportedLanguages, fallbackLanguage, languageStrategies = [], languageHooks = [], }) {
         checkSupportedLanguages(supportedLanguages);
         this.supportedLanguages = supportedLanguages;
         this.fallbackLanguage = fallbackLanguage;
         const initialLanguage = determineInitialLanguage(languageStrategies, supportedLanguages, fallbackLanguage);
-        this.currentLanguage = $state(initialLanguage);
+        this.#currentLanguage = $state(initialLanguage);
         this.locale = $derived({
-            language: this.currentLanguage,
+            language: this.#currentLanguage,
             fallback: this.fallbackLanguage,
             pluralRules: new Intl.PluralRules(this.currentLanguage),
         });
-        $effect(() => {
-            for (const hook of languageHooks) {
-                hook(this.currentLanguage);
-            }
-        });
+        this.languageHooks = languageHooks;
+    }
+    get currentLanguage() {
+        return this.#currentLanguage;
+    }
+    set currentLanguage(language) {
+        this.#currentLanguage = language;
+        for (const hook of this.languageHooks) {
+            hook(this.currentLanguage);
+        }
     }
     define(texts) {
         return new Dictionary(() => this.locale, texts);

package/package.json

@@ -1,6 +1,16 @@
 {
   "name": "svelte-component-i18n",
-  "version": "0.1.0",
+  "version": "0.1.3",
+  "license": "BSD-3-Clause",
+  "description": "Lightweight internationalization library for Svelte.",
+  "author": "Lukas Dietrich <lukas@lukasdietrich.com>",
+  "repository": "github:lukasdietrich/svelte-component-i18n",
+  "keywords": [
+    "svelte",
+    "i18n",
+    "internationalization",
+    "translation"
+  ],
   "scripts": {
     "dev": "vite dev",
     "build": "vite build && npm run prepack",
@@ -55,8 +65,5 @@
     "typescript-eslint": "^8.48.1",
     "vite": "^7.2.6",
     "vitest": "^4.0.15"
-  },
-  "keywords": [
-    "svelte"
-  ]
+  }
 }