@intlayer/docs 9.4.0 → 9.4.2

package/docs/nl/intlayer_with_storybook.md

@@ -90,8 +90,6 @@ bun add vite-intlayer --dev
 | `react-intlayer` | React-bindingen - `IntlayerProvider`, `useIntlayer` hook       |
 | `vite-intlayer`  | Vite-plugin - bewaakt en compileert inhoudsdeclaratiebestanden |
 
----
-
 </Step>
 
 <Step number={2} title="Een Intlayer-configuratie aanmaken">
@@ -121,8 +119,6 @@ export default config;
 
 > Zie voor de volledige lijst met opties de [configuratiereferentie](https://github.com/aymericzip/intlayer/blob/main/docs/docs/nl/configuration.md).
 
----
-
 </Step>
 
 <Step number={3} title="De Vite-plugin toevoegen aan Storybook">
@@ -170,8 +166,6 @@ export default config;
 
 De `intlayer()` plugin bewaakt uw `*.content.ts` bestanden and bouwt automatisch woordenboeken opnieuw op wanneer ze veranderen tijdens de Storybook-ontwikkeling.
 
----
-
 </Step>
 
 <Step number={4} title="De `IntlayerProvider` decorator en een locale-werkbalk toevoegen">
@@ -256,8 +250,6 @@ bun add intlayer react-intlayer
 bun add @intlayer/webpack --dev
 ```
 
----
-
 </Step>
 
 <Step number={2} title="Een Intlayer-configuratie aanmaken">
@@ -280,8 +272,6 @@ const config: IntlayerConfig = {
 export default config;
 ```
 
----
-
 </Step>
 
 <Step number={3} title="Webpack van Storybook configureren">
@@ -309,8 +299,6 @@ const config: StorybookConfig = {
 export default config;
 ```
 
----
-
 </Step>
 
 <Step number={4} title="De `IntlayerProvider` decorator en een locale-werkbalk toevoegen">

package/docs/nl/intlayer_with_vanilla.md

@@ -412,7 +412,8 @@ const unsubscribe = useDictionaryDynamic(
 ```
 
 > Opmerking: `useDictionaryDynamic` vereist dat de woordenboeken beschikbaar zijn als afzonderlijke ESM-bestanden. Deze aanpak wordt doorgaans gebruikt als je een webserver hebt die de woordenboeken serveert.
-> </Step>
+
+</Step>
 
 </Steps>
 

package/docs/nl/introduction.md

@@ -93,7 +93,6 @@ export const MyComponent: FC = () => {
 Vergeleken met grote oplossingen zoals `next-intl` of `i18next`, is Intlayer een oplossing met geïntegreerde optimalisaties zoals:
 
 <AccordionGroup>
-
 <Accordion header="Bundelgrootte (Bundle size)">
 
 Laad in plaats van enorme JSON-bestanden naar uw pagina's alleen de benodigde content. Intlayer helpt **uw bundel- en paginagroottes met wel 50% te verkleinen**.

package/docs/pl/analytics.md

@@ -103,6 +103,21 @@ export default config;
 
 Jeśli hostujesz sam Intlayer (self-host), analityka automatycznie wskazuje na twoją własną instancję, jako że współdzieli parametr `editor.backendURL`.
 
+### Wywoływanie API z przeglądarki
+
+Ten sam token zasila mały klient niewymagający danych uwierzytelniających, dzięki czemu strona statyczna lub SPA może odczytać zawartość swojego CMS w czasie działania bez serwera, bez server action i bez żadnego sekretu w paczce (bundle):
+
+```ts fileName="content.ts"
+import { createPublicClient } from "@intlayer/api/public";
+
+const client = createPublicClient();
+
+const keys = await client.getDictionaryKeys();
+const [navbar] = await client.getDictionaries(["navbar"]);
+```
+
+Uwierzytelnia się on samodzielnie na podstawie `editor.clientId`: wymiana, buforowanie (caching) i odnawianie są obsługiwane wewnętrznie. Zakresy (scopes) ograniczają to, do czego ma dostęp: opublikowaną zawartość słowników oraz przyjmowanie zdarzeń analityki. Wszystko inne (wysyłanie słowników, odczyt projektu, wydawanie kredytów AI) wymaga prawdziwych danych uwierzytelniających, a więc serwera lub zalogowanego użytkownika.
+
 ### Rezygnacja (opt-out)
 
 Opcjonalny blok `analytics` pozwala dostroić — lub wyłączyć — zbieranie danych:
@@ -123,17 +138,6 @@ export default config;
 
 Odinstalowanie `@intlayer/analytics` daje ten sam efekt co `enabled: false`. Pełną listę pól znajdziesz w [dokumentacji konfiguracji](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/configuration.md).
 
-## Wsparcie dla Frameworków
-
-Analytics jest wpięty w udostępniony `IntlayerProvider` z `react-intlayer`, stąd jest dostępny już dziś w każdym miejscu, w którym ten provider jest używany:
-
-| Framework                                                | Status                                                                                               |
-| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
-| React                                                    | ✅ Dostępne                                                                                          |
-| Next.js (`next-intlayer`)                                | ✅ Dostępne (poprzez `react-intlayer`)                                                               |
-| React Native / Expo (`react-native-intlayer`)            | ✅ Dostępne (poprzez `react-intlayer`)                                                               |
-| Vue, Svelte, Angular, Solid, Preact, Lit, Astro, Vanilla | 🚧 Zaplanowano — ten sam klient, podpięcia na poziomie providera wzorujące się na `@intlayer/editor` |
-
 ## Użycie
 
 ### Automatyczne śledzenie na poziomie providera
@@ -145,6 +149,126 @@ Brak konieczności modyfikowania kodu. Po zainstalowaniu pakietu `@intlayer/anal
 - rejestrować `page_view` za każdą zmianą lokalizacji,
 - uruchamiać cykl „wypychania” (flush) zdarzeń po około 20 sekundach oraz natychmiast, gdy zakładka zostanie zamknięta (za pośrednictwem `navigator.sendBeacon`, z trybem zapasowym (fallback) do `fetch(..., { keepalive: true })`).
 
+Punkt wejścia różni się w zależności od frameworka, ale w każdym przypadku jest to to samo miejsce, którego już używasz do skonfigurowania Intlayer, więc nie ma nic więcej do dodania:
+
+<Tabs group="framework">
+  <Tab label="React" value="react">
+
+    `IntlayerProvider` montuje dostawcę analityki wewnętrznie.
+
+    ```tsx fileName="App.tsx"
+    import { IntlayerProvider } from "react-intlayer";
+
+    const App = () => (
+      <IntlayerProvider>
+        <Router />
+      </IntlayerProvider>
+    );
+    ```
+
+  </Tab>
+  <Tab label="Next.js" value="nextjs">
+
+    `next-intlayer` eksportuje ponownie `IntlayerProvider` z React, więc analityka jest podłączona w ten sam sposób.
+
+    ```tsx fileName="app/[locale]/layout.tsx"
+    import { IntlayerProvider } from "next-intlayer";
+
+    const LocaleLayout = ({ children }) => (
+      <IntlayerProvider>{children}</IntlayerProvider>
+    );
+
+    export default LocaleLayout;
+    ```
+
+  </Tab>
+  <Tab label="Vue" value="vue">
+
+    Wtyczka `intlayer` rejestruje hooki analityki w cyklu życia komponentu głównego.
+
+    ```javascript fileName="main.js"
+    import { createApp } from "vue";
+    import { intlayer } from "vue-intlayer";
+    import App from "./App.vue";
+
+    const app = createApp(App);
+
+    app.use(intlayer);
+
+    app.mount("#app");
+    ```
+
+    > Przy Nuxt, `nuxt-intlayer` instaluje wtyczkę za ciebie: nie musisz nic robić.
+
+  </Tab>
+  <Tab label="Svelte" value="svelte">
+
+    `setupIntlayer()` uruchamia analitykę z komponentu, który konfiguruje Intlayer.
+
+    ```svelte fileName="src/routes/[[locale=locale]]/+layout.svelte"
+    <script lang="ts">
+      import { setupIntlayer } from "svelte-intlayer";
+      import type { Snippet } from "svelte";
+
+      let { children, data }: { children: Snippet, data: LayoutData } = $props();
+
+      $effect(() => {
+        setupIntlayer(data.locale);
+      });
+    </script>
+
+    {@render children()}
+    ```
+
+  </Tab>
+  <Tab label="Preact" value="preact">
+
+    `IntlayerProvider` montuje dostawcę analityki wewnętrznie.
+
+    ```tsx fileName="app.tsx"
+    import { IntlayerProvider } from "preact-intlayer";
+
+    const App = () => (
+      <IntlayerProvider>
+        <Router />
+      </IntlayerProvider>
+    );
+    ```
+
+  </Tab>
+  <Tab label="Solid" value="solid">
+
+    `IntlayerProvider` montuje dostawcę analityki leniwie (lazy), dzięki czemu ten fragment kodu (chunk) pozostaje poza krytyczną ścieżką.
+
+    ```tsx fileName="App.tsx"
+    import { IntlayerProvider } from "solid-intlayer";
+
+    const App = () => (
+      <IntlayerProvider>
+        <Router />
+      </IntlayerProvider>
+    );
+    ```
+
+  </Tab>
+  <Tab label="Angular" value="angular">
+
+    `provideIntlayer()` zawiera już `provideIntlayerAnalytics()`.
+
+    ```ts fileName="app.config.ts"
+    import { provideIntlayer } from "angular-intlayer";
+    import type { ApplicationConfig } from "@angular/core";
+
+    export const appConfig: ApplicationConfig = {
+      providers: [provideIntlayer()],
+    };
+    ```
+
+    > Używaj `provideIntlayerAnalytics()` samodzielnie tylko wtedy, gdy zarządzasz providerami indywidualnie.
+
+  </Tab>
+</Tabs>
+
 ### Automatyczne śledzenie na poziomie węzła
 
 Za każdym razem, gdy `useIntlayer` rozwiąże jakiś fragment treści do wyświetlenia, interpreter raportuje zdarzenie typu `content_exposure` dla odpowiedniego elementu tj. zbiór `dictionaryKey` + lokalizacja (locale) + precyzyjna ścieżka klucza (key path) — ponownie, nie ma potrzeby zmieniania kodu. Powielone zdarzenia tego samego węzła pojawiające się w cyklu wypychania zostają zgrupowane do 1 zapytania razem z właściwością `count` — dzięki czemu lista z renderowaniem wykonywanym po 50 razy nie wypycha 50 razy osobnego zapytania.
@@ -153,29 +277,368 @@ Za każdym razem, gdy `useIntlayer` rozwiąże jakiś fragment treści do wyświ
 
 Wykorzystaj `useConversion()`, aby przypisać cel do wariantu, z którym wchodzono w interakcję w czasie sesji:
 
-```tsx fileName="CTAButton.tsx" codeFormat="tsx"
-import { useConversion } from "react-intlayer";
-
-const CTAButton = () => {
-  const trackConversion = useConversion();
+<Tabs group="framework">
+  <Tab label="React" value="react">
+
+    ```tsx fileName="CTAButton.tsx"
+    import { useConversion } from "react-intlayer";
+
+    const CTAButton = () => {
+      const trackConversion = useConversion();
+
+      return (
+        <button
+          onClick={() =>
+            trackConversion({
+              experimentKey: "homepage-hero",
+              variant: "black_friday",
+              goal: "cta_click",
+            })
+          }
+        >
+          Rozpocznij
+        </button>
+      );
+    };
+    ```
+
+  </Tab>
+  <Tab label="Next.js" value="nextjs">
+
+    ```tsx fileName="CTAButton.tsx"
+    "use client";
+
+    import { useConversion } from "next-intlayer";
+
+    const CTAButton = () => {
+      const trackConversion = useConversion();
+
+      return (
+        <button
+          onClick={() =>
+            trackConversion({
+              experimentKey: "homepage-hero",
+              variant: "black_friday",
+              goal: "cta_click",
+            })
+          }
+        >
+          Rozpocznij
+        </button>
+      );
+    };
+    ```
+
+    > `useConversion` to hook kliencki: oznacz komponent jako `"use client"`.
+
+  </Tab>
+  <Tab label="Vue" value="vue">
+
+    ```vue fileName="CTAButton.vue"
+    <script setup lang="ts">
+    import { useConversion } from "vue-intlayer";
+
+    const trackConversion = useConversion();
+    </script>
+
+    <template>
+      <button
+        @click="
+          trackConversion({
+            experimentKey: 'homepage-hero',
+            variant: 'black_friday',
+            goal: 'cta_click',
+          })
+        "
+      >
+        Rozpocznij
+      </button>
+    </template>
+    ```
+
+  </Tab>
+  <Tab label="Svelte" value="svelte">
+
+    ```svelte fileName="CTAButton.svelte"
+    <script lang="ts">
+      import { useConversion } from "svelte-intlayer";
+
+      const trackConversion = useConversion();
+    </script>
 
-  return (
     <button
-      onClick={() =>
+      onclick={() =>
         trackConversion({
           experimentKey: "homepage-hero",
           variant: "black_friday",
           goal: "cta_click",
-        })
-      }
+        })}
     >
       Rozpocznij
     </button>
+    ```
+
+  </Tab>
+  <Tab label="Preact" value="preact">
+
+    ```tsx fileName="CTAButton.tsx"
+    import { useConversion } from "preact-intlayer";
+
+    const CTAButton = () => {
+      const trackConversion = useConversion();
+
+      return (
+        <button
+          onClick={() =>
+            trackConversion({
+              experimentKey: "homepage-hero",
+              variant: "black_friday",
+              goal: "cta_click",
+            })
+          }
+        >
+          Rozpocznij
+        </button>
+      );
+    };
+    ```
+
+  </Tab>
+  <Tab label="Solid" value="solid">
+
+    ```tsx fileName="CTAButton.tsx"
+    import { useConversion } from "solid-intlayer";
+
+    const CTAButton = () => {
+      const trackConversion = useConversion();
+
+      return (
+        <button
+          onClick={() =>
+            trackConversion({
+              experimentKey: "homepage-hero",
+              variant: "black_friday",
+              goal: "cta_click",
+            })
+          }
+        >
+          Rozpocznij
+        </button>
+      );
+    };
+    ```
+
+  </Tab>
+  <Tab label="Angular" value="angular">
+
+    ```typescript fileName="cta-button.component.ts"
+    import { Component } from "@angular/core";
+    import { useConversion } from "angular-intlayer";
+
+    @Component({
+      selector: "app-cta-button",
+      template: `<button (click)="onClick()">Rozpocznij</button>`,
+    })
+    export class CtaButtonComponent {
+      private trackConversion = useConversion();
+
+      onClick() {
+        this.trackConversion({
+          experimentKey: "homepage-hero",
+          variant: "black_friday",
+          goal: "cta_click",
+        });
+      }
+    }
+    ```
+
+  </Tab>
+</Tabs>
+
+### Odbieranie wariantu bezpośrednio po stronie klienta
+
+`useExperiment()` przypisuje sesję do wariantu i rejestruje ekspozycję, która staje się mianownikiem współczynnika konwersji. Pokazuj poddrzewo zależne od wariantu dopiero, gdy `isAssigned` ma wartość prawda, aby żaden odwiedzający nie zobaczył krótkiego mignięcia wariantu kontrolnego, zanim przypisanie zostanie rozstrzygnięte:
+
+<Tabs group="framework">
+  <Tab label="React" value="react">
+
+    `variant` jest zwykłym ciągiem znaków (string).
+
+    ```tsx fileName="Hero.tsx"
+    import { useExperiment } from "react-intlayer";
+    import { HeroBanner } from "./HeroBanner";
+
+    export const Hero = () => {
+      const { variant, isAssigned } = useExperiment("homepage-hero", [
+        "default",
+        "black_friday",
+      ]);
+
+      if (!isAssigned) return null;
+
+      return <HeroBanner variant={variant} />;
+    };
+    ```
+
+  </Tab>
+  <Tab label="Next.js" value="nextjs">
+
+    `variant` jest zwykłym ciągiem znaków (string). Przypisanie następuje w przeglądarce, więc komponent musi być komponentem klienckim.
+
+    ```tsx fileName="Hero.tsx"
+    "use client";
+
+    import { useExperiment } from "next-intlayer";
+    import { HeroBanner } from "./HeroBanner";
+
+    export const Hero = () => {
+      const { variant, isAssigned } = useExperiment("homepage-hero", [
+        "default",
+        "black_friday",
+      ]);
+
+      if (!isAssigned) return null;
+
+      return <HeroBanner variant={variant} />;
+    };
+    ```
+
+  </Tab>
+  <Tab label="Vue" value="vue">
+
+    `variant` i `isAssigned` to `Ref`y.
+
+    ```vue fileName="Hero.vue"
+    <script setup lang="ts">
+    import { useExperiment } from "vue-intlayer";
+    import HeroBanner from "./HeroBanner.vue";
+
+    const { variant, isAssigned } = useExperiment("homepage-hero", [
+      "default",
+      "black_friday",
+    ]);
+    </script>
+
+    <template>
+      <HeroBanner v-if="isAssigned" :variant="variant" />
+    </template>
+    ```
+
+  </Tab>
+  <Tab label="Svelte" value="svelte">
+
+    `variant` i `isAssigned` to store'y: odczytaj je z prefiksem `$`.
+
+    ```svelte fileName="Hero.svelte"
+    <script lang="ts">
+      import { useExperiment } from "svelte-intlayer";
+      import HeroBanner from "./HeroBanner.svelte";
+
+      const { variant, isAssigned } = useExperiment("homepage-hero", [
+        "default",
+        "black_friday",
+      ]);
+    </script>
+
+    {#if $isAssigned}
+      <HeroBanner variant={$variant} />
+    {/if}
+    ```
+
+  </Tab>
+  <Tab label="Preact" value="preact">
+
+    `variant` jest zwykłym ciągiem znaków (string).
+
+    ```tsx fileName="Hero.tsx"
+    import { useExperiment } from "preact-intlayer";
+    import { HeroBanner } from "./HeroBanner";
+
+    export const Hero = () => {
+      const { variant, isAssigned } = useExperiment("homepage-hero", [
+        "default",
+        "black_friday",
+      ]);
+
+      if (!isAssigned) return null;
+
+      return <HeroBanner variant={variant} />;
+    };
+    ```
+
+  </Tab>
+  <Tab label="Solid" value="solid">
+
+    `variant` i `isAssigned` to `Accessor`y: wywołaj je, aby odczytać wartość.
+
+    ```tsx fileName="Hero.tsx"
+    import { useExperiment } from "solid-intlayer";
+    import { Show } from "solid-js";
+    import { HeroBanner } from "./HeroBanner";
+
+    export const Hero = () => {
+      const { variant, isAssigned } = useExperiment("homepage-hero", [
+        "default",
+        "black_friday",
+      ]);
+
+      return (
+        <Show when={isAssigned()}>
+          <HeroBanner variant={variant()} />
+        </Show>
+      );
+    };
+    ```
+
+  </Tab>
+  <Tab label="Angular" value="angular">
+
+    `variant` i `isAssigned` to `Signal`y: wywołaj je, aby odczytać wartość.
+
+    ```typescript fileName="hero.component.ts"
+    import { Component } from "@angular/core";
+    import { useExperiment } from "angular-intlayer";
+    import { HeroBannerComponent } from "./hero-banner.component";
+
+    @Component({
+      selector: "app-hero",
+      imports: [HeroBannerComponent],
+      template: `@if (experiment.isAssigned()) {
+        <app-hero-banner [variant]="experiment.variant()" />
+      }`,
+    })
+    export class HeroComponent {
+      experiment = useExperiment("homepage-hero", ["default", "black_friday"]);
+    }
+    ```
+
+  </Tab>
+</Tabs>
+
+Wagi są opcjonalne — przekaż jedną na wariant, aby zmienić proporcje podziału, np. `useExperiment("homepage-hero", ["default", "black_friday"], [9, 1])`.
+
+Komponent dziecko odczytuje następnie pasujący [Wariant (Variant)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/dynamic_dictionaries/variants.md) słownika:
+
+```tsx fileName="HeroBanner.tsx"
+import { useIntlayer } from "react-intlayer";
+
+export const HeroBanner = ({ variant }: { variant: string }) => {
+  const { headline, cta } = useIntlayer("hero-banner", { variant });
+
+  return (
+    <section>
+      <h1>{headline}</h1>
+      <a>{cta}</a>
+    </section>
   );
 };
 ```
 
-### Odbieranie wariantu bezpośrednio po stronie klienta
+> Odczytanie wariantu w **komponencie dziecku** sprawia, że działa to poza React: w Vue, Svelte, Solid i Angular selektor przekazany do `useIntlayer` jest przechwytywany w momencie konfigurowania komponentu, więc odczyt musi nastąpić w komponencie, który montuje się dopiero, gdy wariant jest już znany.
+
+Jeśli eksperyment obejmuje całą stronę, a nie pojedynczy słownik, przenieś wariant na providera — zobacz [Ambient variant](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/dynamic_dictionaries/variants.md#ambient-variant). Każdy `useIntlayer` poniżej rozwiąże się wtedy względem niego bez zmian w miejscu wywołania.
+
+Jeśli potrzebujesz surowego przypisania poza komponentem, skorzystaj bezpośrednio z klienta:
 
 ```tsx fileName="useHeroVariant.ts" codeFormat="tsx"
 import { getGlobalAnalyticsClient } from "@intlayer/analytics/client";
@@ -187,6 +650,8 @@ const variant = client?.getVariant("homepage-hero", [
 ]);
 ```
 
+> `getVariant` tylko przypisuje — nie rejestruje ekspozycji. Preferuj `useExperiment()`, w przeciwnym razie współczynnik konwersji nie będzie miał mianownika.
+
 ## Prywatność & Wydajność
 
 - **Z założenia anonimowe (Anonymous by design)**: sesje definiowane są losowymi unikalnymi indentyfikatorami (rotating ids), i backend nie przetwarza danych tak mocno, by przetrzymywać oryginał i nigdy IP urządzenia; pozostawia jedynie odcienie, zjawisko **SHA-256 hash**.
@@ -234,6 +699,8 @@ const cms = createIntlayerCMS();
 const { data: audience } = await analyticsEndpoint(cms).getAudience(30);
 ```
 
+> **Tylko po stronie serwera.** `createIntlayerCMS()` uwierzytelnia się za pomocą `clientId` + `clientSecret`, a sekret nigdy nie jest dostępny w przeglądarce: ten fragment kodu wysyłałby nieuwierzytelnione żądania, gdyby działał tam. Trzymaj go w route handlerze, server action lub skrypcie.
+
 ## Przydatne linki
 
 - [Słowniki dynamiczne – Kolekcje & Warianty (Dynamic Dictionaries)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/dynamic_dictionaries/index.md)