@tolgee/svelte 5.0.0-alpha.1 → 5.0.0-alpha.3

package/CHANGELOG.md

@@ -3,6 +3,28 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [5.0.0-alpha.3](https://github.com/tolgee/tolgee-js/compare/v4.9.3...v5.0.0-alpha.3) (2023-01-11)
+
+
+* feat!: Complete redesign, namespaces support, refactor (#3109) ([1978b91](https://github.com/tolgee/tolgee-js/commit/1978b917dfec2df89f59de4cd10b632920c47e57)), closes [#3109](https://github.com/tolgee/tolgee-js/issues/3109)
+
+
+### BREAKING CHANGES
+
+* Complete redesign, brand new API
+
+
+
+
+
+# 5.0.0-alpha.2 (2023-01-09)
+
+**Note:** Version bump only for package @tolgee/svelte
+
+
+
+
+
 # 5.0.0-alpha.1 (2022-11-29)
 
 

package/README.md

@@ -1,54 +1,97 @@
-# Tolgee for Svelte
+<!-- This file was generated using pnpm generate-readmes script 
+        
+        Don't edit this file. Edit the README.md.njk. Macros can be found in readmeMacros/macros.njk
+        
+        -->
+
+<h1 align="center" style="border-bottom: none">
+    <b>
+        <a href="https://tolgee.io">Tolgee for Svelte</a><br>
+    </b>
+    The Tolgee i18n SDK for Svelte
+    <br>
+</h1>
+
+<div align="center">
+
+[![Logo](https://user-images.githubusercontent.com/18496315/188628892-33fcc282-26f1-4035-8105-95952bd93de9.svg)](https://tolgee.io)
+
+Tolgee is an open-source alternative to Crowdin, Phrase, or Lokalise with its very own revolutionary integrations.
 
 ![test workflow](https://github.com/tolgee/tolgee-js/actions/workflows/test.yml/badge.svg)
-![@tolgee/svelte version](https://img.shields.io/npm/v/@tolgee/svelte?label=%40tolgee%2Fsvelte)
+
+![@tolgee/svelte version](https://img.shields.io/npm/v/@tolgee/svelte?label=@tolgee/svelte)
+
 ![types typescript](https://img.shields.io/badge/Types-Typescript-blue)
+![typescript](https://img.shields.io/github/languages/top/tolgee/tolgee-js)
 ![licence](https://img.shields.io/github/license/tolgee/tolgee-js)
-[![twitter](https://img.shields.io/twitter/follow/Tolgee_i18n?style=social)](https://twitter.com/Tolgee_i18n)
-[![github stars](https://img.shields.io/github/stars/tolgee/tolgee-js?style=social)](https://github.com/tolgee/tolgee-js)
+[![github stars](https://img.shields.io/github/stars/tolgee/tolgee-js?style=social&label=Tolgee%20JS)](https://github.com/tolgee/tolgee-js)
+[![github stars](https://img.shields.io/github/stars/tolgee/server?style=social&label=Tolgee%20Server)](https://github.com/tolgee/server)
+[![Github discussions](https://img.shields.io/github/discussions/tolgee/tolgee-platform)](https://github.com/tolgee/tolgee-platform/discussions)
+</div>
 
-Svelte integration library (SDK) of Tolgee. For more information about using Tolgee with Svelte, visit our
-[documentation website 📖](https://tolgee.io/docs).
+<div align="center">
 
-[<img src="https://raw.githubusercontent.com/tolgee/documentation/main/tolgee_logo_text.svg" alt="Tolgee" width="200" />](https://tolgee.io)
+[<img src="https://img.shields.io/badge/-Facebook-424549?style=social&logo=facebook" height=25 />](https://www.facebook.com/Tolgee.i18n)
+[<img src="https://img.shields.io/badge/-Twitter-424549?style=social&logo=twitter" height=25 />](https://twitter.com/Tolgee_i18n)
+[<img src="https://img.shields.io/badge/-Linkedin-424549?style=social&logo=linkedin" height=25 />](https://www.linkedin.com/company/tolgee)
 
-Lokalize (translate) your Svelte projects to multiple languages with Tolgee. Integration of Tolgee is extremely simple!
-🇯🇵 🇰🇷 🇩🇪 🇨🇳 🇺🇸 🇫🇷 🇪🇸 🇮🇹 🇷🇺 🇬🇧
+**Become part of the family. Join [slack channel <img src="https://img.shields.io/badge/-Tolgee Comunity-424549?style=social&logo=slack" height=25 />](https://join.slack.com/t/tolgeecommunity/shared_invite/zt-195isb5u8-_RcSRgVJfvgsPpOBIok~IQ)**
 
-## Features
+</div>
 
-- All in One localization solution for your Svelte application 🙌
-- Out of box in-context localization 🎉
-- Automated screenshot generation 📷
-- Translation management platform 🎈
-- Supports SSR with svelte kit 🎉
-- Open-source 🔥
 
-## Installation
 
-First, install the package.
+# What is Tolgee for Svelte?
+Svelte integration library of Tolgee. With this package, it's super simple to add i18n to your Svelte app!
+For more information about using Tolgee with Svelte, visit the [docs 📖](https://tolgee.io/integrations/svelte).
 
-    npm install @tolgee/svelte
+Localize (translate) your Svelte or SvelteKit projects to multiple languages with Tolgee.
+Integration of Tolgee is extremely simple! 🇯🇵 🇰🇷 🇩🇪 🇨🇳 🇺🇸 🇫🇷 🇪🇸 🇮🇹 🇷🇺 🇬🇧
 
-Then use the library in your app:
 
-```sveltehtml
+## Quick links
+- [Tolgee for Angular docs](https://tolgee.io/js-sdk/5.0.0-alpha.1/integrations/svelte/installation)
+- [Tolgee JS SDK docs](https://tolgee.io/js-sdk)
+- [Tolgee Website](https://tolgee.io)
+    - Product (Learn more about the great features)
+        - [Dev tools](https://tolgee.io/features/dev-tools)
+        - [Translation assistance](https://tolgee.io/features/translation-assistance)
+        - [Collaboration](https://tolgee.io/features/collaboration)
+- [Tolgee platform docs](https://tolgee.io/platform)
+  
 
-<script lang="ts">
-  import { TolgeeProvider } from "@tolgee/svelte";
-  import type { TolgeeConfig } from "@tolgee/web";
 
-  const tolgeeConfig = {
-    preloadFallback: true,
+## Installation
+
+```
+npm install @tolgee/svelte
+```
 
-    // when using SvelteKit and .env, otherwise you can set those params directly or use some dotenv library
-    apiUrl: import.meta.env.VITE_TOLGEE_API_KEY,
-    apiKey: import.meta.env.VITE_TOLGEE_API_KEY
-  } as TolgeeConfig;
+
+Then use the library in your app:
+
+```svelte
+<script lang="ts">
+  import {
+    TolgeeProvider,
+    Tolgee,
+    SveltePlugin,
+    FormatSimple,
+  } from '@tolgee/svelte';
+
+  const tolgee = Tolgee()
+    .use(SveltePlugin())
+    .use(FormatSimple())
+    .init({
+      apiUrl: import.meta.env.VITE_TOLGEE_API_URL,
+      apiKey: import.meta.env.VITE_TOLGEE_API_KEY,
+      language: 'en',
+    });
 </script>
 
-<TolgeeProvider config={tolgeeConfig}>
-  <div slot="loading-fallback">Loading...</div>
+<TolgeeProvider {tolgee}>
+  <div slot="fallback">Loading...</div>
   <slot />
 </TolgeeProvider>
 ```
@@ -59,55 +102,120 @@ To translate texts using Tolgee Svelte integration, you can use `T` component or
 
 ### T component
 
-```sveltehtml
-
+```svelte
 <script>
-  import { T } from "@tolgee/svelte";
+  import { T } from '@tolgee/svelte';
 </script>
 
-
 <T keyName="key" defaultValue="This is default" />
 ```
 
 ### getTranslate function
 
-The `getTranslate` function returns store containing the function, which actually translates your key.
+The `getTranslate` function returns a store containing the function, which translates your key.
 
-```sveltehtml
+```svelte
 <script>
-  import { getTranslate } from "@tolgee/svelte";
+  import { getTranslate } from '@tolgee/svelte';
 
-  const t = getTranslate();
+  const { t } = getTranslate();
 </script>
 
-
-{$t({ key: "this_is_a_key", parameters: { key: "value", key2: "value2" } })}
+{$t('this_is_a_key', { key: 'value', key2: 'value2' })}
 ```
 
 ### Changing the language
 
-To change the current language, use `getLanguageStore` method. For example, you can bind it to select value.
+To change the current language, use `getLanguageStore` method. For example, you can bind it to a select value.
 
-```sveltehtml
+```svelte
 <script lang="ts">
-  import { getLanguageStore } from "@tolgee/svelte";
+  import { getTolgee } from '@tolgee/svelte';
+
+  const tolgee = getTolgee(['language']);
 
-  const languageStore = getLanguageStore();
+  function handleLanguageChange(e) {
+    $tolgee.changeLanguage(e.currentTarget.value);
+  }
 </script>
 
-<select bind:value={$languageStore} class="lang-selector">
-  <option value="en">🇬🇧 English</option>
-  <option value="cs">🇨🇿 česky</option>
-  <option value="fr">🇫🇷 français</option>
-  <option value="de">🇩🇪 Deutsch</option>
+<select value={$tolgee.getLanguage()} on:change={handleLanguageChange}>
+  ...
 </select>
 ```
 
+
 ## Prerequisites
 
-1. You have some Svelte based project
-2. You have generated API key from [Tolgee Cloud](https://app.tolgee.io) or self-hosted Tolgee instance.
+1. You have some Svelte-based project
+2. You have generated an API key from [Tolgee Cloud](https://app.tolgee.io) or a self-hosted Tolgee instance.
+   
+
+
+## Why to use Tolgee?
+Because it saves a lot of time, you would spend on localization tasks without it. Because it enables you to provide perfectly translated software.
+
+### Features
+
+- All-in-one localization solution for your JS application 🙌
+- Out-of-box in-context localization 🎉
+- Automated screenshot generation 📷
+- Translation management platform 🎈
+- Open-source 🔥
+
+![Frame 47](https://user-images.githubusercontent.com/18496315/188637819-ac4eb02d-7859-4ca8-9807-27818a52782d.png)
+Read more on the [Tolgee website](https://tolgee.io)
+
+
+## Development
+
+We welcome your PRs.
+
+To develop the package locally:
+1. Clone [the repository](https://github.com/tolgee/tolgee-js)
+1. Install the packages in the repository root
+```
+pnpm install
+```
+
+
+1. Run the development script
+```
+pnpm develop:svelte
+```
+This runs the development suite of this monorepo for the `svelte` integration. The changes in each dependency package are
+automatically built and propagated to the test application, which you can open and play within the browser.
+
+
+
+
+### Testing
+
+To run Jest tests of this package, execute
+```
+npm run test
+```
+In the `/packages/svelte` directory.
+
+
+
+
+### End-to-end (e2e) testing
+To run the e2e tests, simply execute
+```
+pnpm run e2e run svelte
+```
+
+To open and play with e2e tests, run:
+```
+pnpm run e2e open svelte
+```
+
+
+
+## Contributors
 
-## Quick integration guide
+<a href="https://github.com/tolgee/tolgee-platform/graphs/contributors">
+  <img alt="contributors" src="https://contrib.rocks/image?repo=tolgee/tolgee-js"/>
+</a>
 
-Learn more at our [documentation website 📖](https://tolgee.io).

package/README.njk.md

@@ -0,0 +1,102 @@
+{% import "../../readmeMacros/macros.njk.md" as macros %}
+{{ macros.header('Tolgee for Svelte', 'The Tolgee i18n SDK for Svelte', packageName) }}
+
+# What is Tolgee for Svelte?
+Svelte integration library of Tolgee. With this package, it's super simple to add i18n to your Svelte app!
+For more information about using Tolgee with Svelte, visit the [docs 📖](https://tolgee.io/integrations/svelte).
+
+Localize (translate) your Svelte or SvelteKit projects to multiple languages with Tolgee.
+Integration of Tolgee is extremely simple! 🇯🇵 🇰🇷 🇩🇪 🇨🇳 🇺🇸 🇫🇷 🇪🇸 🇮🇹 🇷🇺 🇬🇧
+
+{{ macros.integrationLinks('Tolgee for Angular docs', macros.v5link('integrations/svelte/installation')) }}
+
+{{ macros.installation('svelte') }}
+
+Then use the library in your app:
+
+```svelte
+<script lang="ts">
+  import {
+    TolgeeProvider,
+    Tolgee,
+    SveltePlugin,
+    FormatSimple,
+  } from '@tolgee/svelte';
+
+  const tolgee = Tolgee()
+    .use(SveltePlugin())
+    .use(FormatSimple())
+    .init({
+      apiUrl: import.meta.env.VITE_TOLGEE_API_URL,
+      apiKey: import.meta.env.VITE_TOLGEE_API_KEY,
+      language: 'en',
+    });
+</script>
+
+<TolgeeProvider {tolgee}>
+  <div slot="fallback">Loading...</div>
+  <slot />
+</TolgeeProvider>
+```
+
+## Usage
+
+To translate texts using Tolgee Svelte integration, you can use `T` component or `getTranslate` function.
+
+### T component
+
+```svelte
+<script>
+  import { T } from '@tolgee/svelte';
+</script>
+
+<T keyName="key" defaultValue="This is default" />
+```
+
+### getTranslate function
+
+The `getTranslate` function returns a store containing the function, which translates your key.
+
+```svelte
+<script>
+  import { getTranslate } from '@tolgee/svelte';
+
+  const { t } = getTranslate();
+</script>
+
+{$t('this_is_a_key', { key: 'value', key2: 'value2' })}
+```
+
+### Changing the language
+
+To change the current language, use `getLanguageStore` method. For example, you can bind it to a select value.
+
+```svelte
+<script lang="ts">
+  import { getTolgee } from '@tolgee/svelte';
+
+  const tolgee = getTolgee(['language']);
+
+  function handleLanguageChange(e) {
+    $tolgee.changeLanguage(e.currentTarget.value);
+  }
+</script>
+
+<select value={$tolgee.getLanguage()} on:change={handleLanguageChange}>
+  ...
+</select>
+```
+
+{{ macros.prereq('Svelte') }}
+
+{{ macros.why() }}
+
+## Development
+{{ macros.developmentInstallation() }}
+{{ macros.development('svelte') }}
+
+{{ macros.developmentTesting('/packages/svelte') }}
+
+{{ macros.e2eTesting('svelte') }}
+
+{{ macros.contributors() }}

package/getTolgee.d.ts

@@ -3,6 +3,7 @@ export declare const getTolgee: (events?: TolgeeEvent[]) => {
     subscribe: (this: void, run: import("svelte/store").Subscriber<Readonly<{
         on: import("@tolgee/web").TolgeeOn<keyof import("@tolgee/web").EventType>;
         onNsUpdate: (handler: import("@tolgee/web").Listener<undefined>) => import("@tolgee/web").SubscriptionSelective;
+        setEmmiterActive: (active: boolean) => void;
         getLanguage: () => string;
         getPendingLanguage: () => string;
         changeLanguage: (language: string) => Promise<void>;
@@ -41,8 +42,9 @@ export declare const getTolgee: (events?: TolgeeEvent[]) => {
             fallbackNs?: import("@tolgee/web").FallbackGeneral;
             defaultNs: string;
             staticData?: import("@tolgee/web").TolgeeStaticData;
-            observerOptions: import("@tolgee/web").ObserverOptionsInternal;
             observerType: "invisible" | "text";
+            observerOptions: import("@tolgee/web").ObserverOptionsInternal;
+            onFormatError: import("@tolgee/web").OnFormatError;
         };
         isDev: () => boolean;
         wrap: (params: import("@tolgee/web").WrapperWrapProps) => string;
@@ -57,6 +59,7 @@ export declare const getTolgee: (events?: TolgeeEvent[]) => {
     }>>, invalidate?: (value?: Readonly<{
         on: import("@tolgee/web").TolgeeOn<keyof import("@tolgee/web").EventType>;
         onNsUpdate: (handler: import("@tolgee/web").Listener<undefined>) => import("@tolgee/web").SubscriptionSelective;
+        setEmmiterActive: (active: boolean) => void;
         getLanguage: () => string;
         getPendingLanguage: () => string;
         changeLanguage: (language: string) => Promise<void>;
@@ -95,8 +98,9 @@ export declare const getTolgee: (events?: TolgeeEvent[]) => {
             fallbackNs?: import("@tolgee/web").FallbackGeneral;
             defaultNs: string;
             staticData?: import("@tolgee/web").TolgeeStaticData;
-            observerOptions: import("@tolgee/web").ObserverOptionsInternal;
             observerType: "invisible" | "text";
+            observerOptions: import("@tolgee/web").ObserverOptionsInternal;
+            onFormatError: import("@tolgee/web").OnFormatError;
         };
         isDev: () => boolean;
         wrap: (params: import("@tolgee/web").WrapperWrapProps) => string;
@@ -112,6 +116,7 @@ export declare const getTolgee: (events?: TolgeeEvent[]) => {
     value: Readonly<{
         on: import("@tolgee/web").TolgeeOn<keyof import("@tolgee/web").EventType>;
         onNsUpdate: (handler: import("@tolgee/web").Listener<undefined>) => import("@tolgee/web").SubscriptionSelective;
+        setEmmiterActive: (active: boolean) => void;
         getLanguage: () => string;
         getPendingLanguage: () => string;
         changeLanguage: (language: string) => Promise<void>;
@@ -150,8 +155,9 @@ export declare const getTolgee: (events?: TolgeeEvent[]) => {
             fallbackNs?: import("@tolgee/web").FallbackGeneral;
             defaultNs: string;
             staticData?: import("@tolgee/web").TolgeeStaticData;
-            observerOptions: import("@tolgee/web").ObserverOptionsInternal;
             observerType: "invisible" | "text";
+            observerOptions: import("@tolgee/web").ObserverOptionsInternal;
+            onFormatError: import("@tolgee/web").OnFormatError;
         };
         isDev: () => boolean;
         wrap: (params: import("@tolgee/web").WrapperWrapProps) => string;

package/index.d.ts

@@ -2,6 +2,6 @@ export { default as T } from './T.svelte';
 export { default as getTranslate } from './getTranslate';
 export { default as TolgeeProvider } from './TolgeeProvider.svelte';
 export { getTolgeeContext } from './getTolgeeContext';
-export { SveltePlugin } from './SveltePlugin';
+export { GlobalContextPlugin } from './GlobalContextPlugin';
 export { getTolgee } from './getTolgee';
 export * from '@tolgee/web';

package/index.js

@@ -2,6 +2,6 @@ export { default as T } from './T.svelte';
 export { default as getTranslate } from './getTranslate';
 export { default as TolgeeProvider } from './TolgeeProvider.svelte';
 export { getTolgeeContext } from './getTolgeeContext';
-export { SveltePlugin } from './SveltePlugin';
+export { GlobalContextPlugin } from './GlobalContextPlugin';
 export { getTolgee } from './getTolgee';
 export * from '@tolgee/web';

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@tolgee/svelte",
-  "version": "5.0.0-alpha.1",
+  "version": "5.0.0-alpha.3",
   "dependencies": {
-    "@tolgee/web": "^5.0.0-alpha.1"
+    "@tolgee/web": "5.0.0-alpha.3"
   },
   "devDependencies": {
     "@sveltejs/adapter-auto": "1.0.0-next.65",
@@ -10,8 +10,8 @@
     "@sveltejs/package": "1.0.0-next.1",
     "@testing-library/jest-dom": "^5.16.5",
     "@testing-library/svelte": "^3.2.1",
-    "@tolgee/format-icu": "^5.0.0-alpha.1",
-    "@tolgee/testing": "^5.0.0-alpha.1",
+    "@tolgee/format-icu": "5.0.0-alpha.3",
+    "@tolgee/testing": "5.0.0-alpha.3",
     "@tsconfig/svelte": "^3.0.0",
     "@types/jest": "^28.1.7",
     "@typescript-eslint/eslint-plugin": "^5.34.0",
@@ -42,7 +42,6 @@
   "exports": {
     "./package.json": "./package.json",
     "./GlobalContextPlugin": "./GlobalContextPlugin.js",
-    "./SveltePlugin": "./SveltePlugin.js",
     "./T.svelte": "./T.svelte",
     "./TolgeeProvider.svelte": "./TolgeeProvider.svelte",
     "./getTolgee": "./getTolgee.js",

package/SveltePlugin.d.ts

@@ -1,2 +0,0 @@
-import { type TolgeePlugin, type InContextOptions } from '@tolgee/web';
-export declare const SveltePlugin: (options?: InContextOptions) => TolgeePlugin;

package/SveltePlugin.js

@@ -1,7 +0,0 @@
-import { DevTools, } from '@tolgee/web';
-import { GlobalContextPlugin } from './GlobalContextPlugin';
-export const SveltePlugin = (options) => (tolgee) => {
-    tolgee.addPlugin(DevTools(options));
-    tolgee.addPlugin(GlobalContextPlugin());
-    return tolgee;
-};