@intlayer/docs 9.5.4 → 9.5.6

package/docs/pl/packages/astro-intlayer/exports.md

@@ -1,12 +1,12 @@
 ---
 createdAt: 2026-01-21
-updatedAt: 2026-01-21
+updatedAt: 2026-09-19
 title: Dokumentacja pakietu astro-intlayer
-description: Integracja Astro dla Intlayer, zapewniająca konfigurację routingu zależnego od locale i zarządzanie słownikami.
+description: Integracja Astro dla Intlayer, zapewniająca routing oparty na lokalizacji, middleware, hooki, magazyn klienta i zarządzanie słownikami.
 keywords:
   - astro-intlayer
   - astro
-  - internationalization
+  - internacjonalizacja
   - i18n
 slugs:
   - doc
@@ -14,6 +14,9 @@ slugs:
   - astro-intlayer
   - exports
 history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "Dodano dokumentację hooków useIntlayer, useDictionary, useLocale, middleware i formaterów"
   - version: 8.0.0
     date: 2026-01-21
     changes: "Ujednolicona dokumentacja dla wszystkich eksportów"
@@ -22,7 +25,7 @@ author: aymericzip
 
 # Pakiet astro-intlayer
 
-Pakiet `astro-intlayer` dostarcza niezbędnych narzędzi do integracji Intlayer z aplikacjami Astro. Konfiguruje routing zależny od locale oraz zarządzanie słownikami.
+Pakiet `astro-intlayer` dostarcza narzędzi do integracji Intlayer z aplikacjami Astro. Konfiguruje routing oparty na lokalizacji, zarządzanie słownikami, przepisywanie stron w czasie budowy, middleware zapytań oraz hooki do pobierania wielojęzycznych treści zarówno w komponentach `.astro` renderowanych po stronie serwera, jak i w skryptach klienta.
 
 ## Instalacja
 
@@ -34,22 +37,171 @@ npm install astro-intlayer
 
 ### Integracja
 
-Pakiet `astro-intlayer` udostępnia integrację dla Astro, umożliwiając skonfigurowanie Intlayer w Twoim projekcie.
+Pakiet `astro-intlayer` dostarcza integrację Astro, która konfiguruje Intlayer w projekcie.
 
 Import:
 
 ```tsx
-import "astro-intlayer";
+import { intlayer } from "astro-intlayer";
 ```
 
-lub dodając do `astro.config.mjs`:
+lub import domyślny w `astro.config.mjs`:
 
 ```ts
+import { defineConfig } from "astro/config";
+import intlayer from "astro-intlayer";
+
 export default defineConfig({
   integrations: [intlayer()],
 });
 ```
 
-| Funkcja    | Opis                                                                |
-| ---------- | ------------------------------------------------------------------- |
-| `intlayer` | Integracja dla Astro, która konfiguruje Intlayer w Twoim projekcie. |
+| Funkcja    | Opis                                                                                                                                                                                                     | Powiązana dokumentacja                                                                                        |
+| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `intlayer` | Integracja Astro, która przygotowuje słowniki, konfiguruje wtyczki Vite (aliasy, proxy routingu, usuwanie zbędnego kodu), automatycznie rejestruje middleware oraz generuje wstępnie renderowane strony. | [intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/astro-intlayer/intlayer.md) |
+
+### Hooki (Serwer i Klient)
+
+Import:
+
+```tsx
+import { useIntlayer, useDictionary, useLocale } from "astro-intlayer";
+```
+
+| Hook            | Opis                                                                                                                                                                                      | Powiązana dokumentacja                                                                                                  |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `useIntlayer`   | Pobiera słownik na podstawie klucza i zwraca zlokalizowaną treść. W sekcji frontmatter `.astro` odczytuje lokalizację z `Astro.locals`. W `<script>` klienta korzysta z magazynu klienta. | [useIntlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/astro-intlayer/useIntlayer.md)     |
+| `useDictionary` | Przetwarza obiekt słownika i zwraca treść dla ustalonej lokalizacji. Działa w frontmatter oraz skryptach klienta.                                                                         | [useDictionary](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/astro-intlayer/useDictionary.md) |
+| `useLocale`     | Zwraca aktualną lokalizację, domyślną lokalizację, dostępne lokalizacje oraz funkcję do aktualizacji lokalizacji.                                                                         | [useLocale](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/astro-intlayer/useLocale.md)         |
+
+### Middleware (astro-intlayer/middleware)
+
+Import:
+
+```tsx
+import { onRequest } from "astro-intlayer/middleware";
+```
+
+| Eksport     | Typ                 | Opis                                                                                                                                                                  | Powiązana dokumentacja                                                                                          |
+| ----------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `onRequest` | `MiddlewareHandler` | Middleware Astro, które wykrywa lokalizację zapytania i dołącza `Astro.locals.intlayer`. Rejestrowane automatycznie przez `intlayer()` lub importowane do kompozycji. | [onRequest](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/astro-intlayer/onRequest.md) |
+
+### Narzędzia pomocnicze
+
+Import:
+
+```tsx
+import { getIntlayerLocals } from "astro-intlayer";
+```
+
+| Funkcja             | Opis                                                                                                        | Powiązana dokumentacja |
+| ------------------- | ----------------------------------------------------------------------------------------------------------- | ---------------------- |
+| `getIntlayerLocals` | Funkcja pomocnicza do pobierania obiektu `IntlayerLocals` z kontekstu zapytania poza zakresem Astro.locals. | -                      |
+
+### Narzędzia klienta (astro-intlayer/client)
+
+Import:
+
+```tsx
+import {
+  useIntlayer,
+  useDictionary,
+  useDictionaryDynamic,
+  useLocale,
+  useLocaleStorage,
+  useLocaleCookie,
+  getIntlayer,
+  getDictionary,
+  installIntlayer,
+  setLocaleInStorage,
+  setLocaleCookie,
+  localeInStorage,
+  localeCookie,
+} from "astro-intlayer/client";
+```
+
+Po zaimportowaniu w przeglądarce lub wewnątrz tagów `<script>` klienta, `astro-intlayer` automatycznie mapuje do `astro-intlayer/client` (opartego na `vanilla-intlayer`), zapewniając gettery słowników po stronie klienta, subskrypcje magazynu oraz narzędzia do utrwalania lokalizacji.
+
+### Formatery (astro-intlayer/format)
+
+Import:
+
+```tsx
+import {
+  useIntl,
+  useDate,
+  useNumber,
+  useCurrency,
+  usePercentage,
+  useRelativeTime,
+  useList,
+  useUnit,
+  useCompact,
+} from "astro-intlayer/format";
+```
+
+| Hook              | Opis                                                                                                      |
+| ----------------- | --------------------------------------------------------------------------------------------------------- |
+| `useIntl`         | Zwraca instancję Intl powiązaną z lokalizacją zapytania lub klienta, z obsługą pamięci podręcznej.        |
+| `useDate`         | Zwraca funkcję formatowania daty powiązaną z bieżącą lokalizacją (`Intl.DateTimeFormat`).                 |
+| `useNumber`       | Zwraca funkcję formatowania liczb powiązaną z bieżącą lokalizacją (`Intl.NumberFormat`).                  |
+| `useCurrency`     | Zwraca funkcję formatowania waluty powiązaną z bieżącą lokalizacją.                                       |
+| `usePercentage`   | Zwraca funkcję formatowania wartości procentowych powiązaną z bieżącą lokalizacją.                        |
+| `useRelativeTime` | Zwraca funkcję formatowania czasu względnego powiązaną z bieżącą lokalizacją (`Intl.RelativeTimeFormat`). |
+| `useList`         | Zwraca funkcję formatowania list powiązaną z bieżącą lokalizacją (`Intl.ListFormat`).                     |
+| `useUnit`         | Zwraca funkcję formatowania jednostek powiązaną z bieżącą lokalizacją.                                    |
+| `useCompact`      | Zwraca funkcję kompaktowego formatowania liczb powiązaną z bieżącą lokalizacją (np. `1.5K`).              |
+
+### Narzędzia HTML (astro-intlayer/html)
+
+Import:
+
+```tsx
+import { renderHTML, useHTML, useHTMLRenderer } from "astro-intlayer/html";
+```
+
+| Eksport           | Typ        | Opis                                                               |
+| ----------------- | ---------- | ------------------------------------------------------------------ |
+| `renderHTML`      | `Function` | Samodzielna funkcja narzędziowa do renderowania węzłów HTML.       |
+| `useHTML`         | `Hook`     | Hook do pobierania kontekstu dostawcy HTML oraz konfiguracji.      |
+| `useHTMLRenderer` | `Hook`     | Hook do uzyskania wstępnie skonfigurowanej funkcji renderera HTML. |
+
+### Narzędzia Markdown (astro-intlayer/markdown)
+
+Import:
+
+```tsx
+import {
+  compileMarkdown,
+  renderMarkdown,
+  parseMarkdown,
+  useMarkdown,
+  useMarkdownRenderer,
+} from "astro-intlayer/markdown";
+```
+
+| Eksport               | Typ        | Opis                                                                   |
+| --------------------- | ---------- | ---------------------------------------------------------------------- |
+| `compileMarkdown`     | `Function` | Kompiluje ciągi znaków markdown do postaci ustrukturyzowanej.          |
+| `renderMarkdown`      | `Function` | Renderuje zawartość markdown do węzłów wyjściowych.                    |
+| `parseMarkdown`       | `Function` | Analizuje surową zawartość markdown do drzewa AST.                     |
+| `useMarkdown`         | `Hook`     | Hook do pobierania kontekstu dostawcy markdown.                        |
+| `useMarkdownRenderer` | `Hook`     | Hook do uzyskania wstępnie skonfigurowanej funkcji renderera Markdown. |
+
+### Typy
+
+Import:
+
+```tsx
+import type {
+  IntlayerLocals,
+  UseLocaleProps,
+  UseLocaleResult,
+} from "astro-intlayer";
+```
+
+| Typ               | Opis                                                                                                       |
+| ----------------- | ---------------------------------------------------------------------------------------------------------- |
+| `IntlayerLocals`  | Obiekt dołączony do `Astro.locals.intlayer` zawierający `locale`, `defaultLocale` oraz `availableLocales`. |
+| `UseLocaleProps`  | Opcjonalne właściwości konfiguracyjne akceptowane przez `useLocale()`.                                     |
+| `UseLocaleResult` | Typ zwracany przez `useLocale()`, zapewniający właściwości lokalizacji i metody aktualizacji.              |

package/docs/pl/packages/astro-intlayer/intlayer.md

@@ -0,0 +1,76 @@
+---
+createdAt: 2026-01-21
+updatedAt: 2026-09-19
+title: Dokumentacja integracji intlayer | astro-intlayer
+description: Zobacz, jak skonfigurować i używać integracji Astro intlayer w pliku astro.config.mjs.
+keywords:
+  - intlayer
+  - astro
+  - astro-intlayer
+  - integracja
+  - i18n
+  - Internacjonalizacja
+  - Dokumentacja
+slugs:
+  - doc
+  - packages
+  - astro-intlayer
+  - intlayer
+history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "Zaktualizowano dokumentację integracji o szczegóły middleware i hooków"
+  - version: 8.0.0
+    date: 2026-01-21
+    changes: "Inicjalizacja dokumentacji"
+author: aymericzip
+---
+
+# Dokumentacja integracji Astro intlayer
+
+Integracja `intlayer` dla Astro konfiguruje projekt pod kątem wielojęzyczności (i18n). Odpowiada za przygotowanie słowników w czasie kompilacji, wstrzykiwanie wtyczek Vite, automatyczną rejestrację middleware zapytań oraz generowanie wstępnie renderowanych zlokalizowanych stron.
+
+## Użycie
+
+Dodaj `intlayer()` do pliku `astro.config.mjs`:
+
+```ts fileName="astro.config.mjs"
+import { defineConfig } from "astro/config";
+import { intlayer } from "astro-intlayer";
+
+export default defineConfig({
+  integrations: [intlayer()],
+});
+```
+
+Polecenie codemod Astro CLI (`astro add astro-intlayer`) generuje również domyślny import, który jest obsługiwany:
+
+```ts
+import intlayer from "astro-intlayer";
+```
+
+## Opis
+
+Integracja podłącza się do cyklu życia kompilacji i działania Astro:
+
+1. **Konfiguracja (`astro:config:setup`)**:
+   - **Przygotowanie słowników**: Przygotowuje słowniki Intlayer i wygenerowane typy przed rozpoczęciem kompilacji.
+   - **Wtyczki Vite**: Wstrzykuje wtyczki dla aliasów Vite (umożliwiając bezproblemowy import słowników), proxy routingu lokalizacji oraz czyszczenia kodu.
+   - **Rejestracja middleware**: Automatycznie wstrzykuje `astro-intlayer/middleware` do łańcucha middleware projektu, wypełniając `Astro.locals.intlayer` dla każdego przychodzącego zapytania.
+2. **Zakończenie kompilacji (`astro:build:done`)**:
+   - **Przepisywanie stron**: Analizuje reguły przepisywania zlokalizowanych adresów URL i generuje wstępnie renderowane strony HTML pod odpowiednimi ścieżkami językowymi.
+
+## Co otrzymujesz po instalacji
+
+Po skonfigurowaniu aplikacja Astro może natychmiast korzystać z:
+
+- Hooków `useIntlayer`, `useDictionary` oraz `useLocale` wewnątrz sekcji frontmatter komponentów `.astro`.
+- Obiektu `Astro.locals.intlayer` w endpointach i stronach Astro.
+- Importów po stronie klienta w blokach `<script>`, odzwierciedlających to samo API z reaktywnymi aktualizacjami.
+- Wbudowanych formaterów w module `astro-intlayer/format` (`useDate`, `useNumber`, `useCurrency` itp.).
+
+## Powiązana dokumentacja
+
+- [Hook `useIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/astro-intlayer/useIntlayer.md)
+- [Hook `useLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/astro-intlayer/useLocale.md)
+- [Middleware `onRequest`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/astro-intlayer/onRequest.md)

package/docs/pl/packages/astro-intlayer/onRequest.md

@@ -0,0 +1,76 @@
+---
+createdAt: 2026-09-19
+updatedAt: 2026-09-19
+title: Dokumentacja middleware onRequest | astro-intlayer
+description: Zobacz, jak używać middleware onRequest w aplikacjach Astro do ustalania lokalizacji zapytania i uzupełniania Astro.locals.intlayer.
+keywords:
+  - onRequest
+  - middleware
+  - astro
+  - astro-intlayer
+  - Astro.locals
+  - Internacjonalizacja
+  - Dokumentacja
+slugs:
+  - doc
+  - packages
+  - astro-intlayer
+  - onRequest
+history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "Inicjalizacja dokumentacji"
+author: aymericzip
+---
+
+# Dokumentacja middleware Astro onRequest
+
+Middleware `onRequest` z modułu `astro-intlayer/middleware` określa lokalizację każdego przychodzącego zapytania HTTP i uzupełnia obiekt `Astro.locals.intlayer`.
+
+Po zarejestrowaniu integracji `intlayer()` w pliku `astro.config.mjs`, to middleware jest wstrzykiwane automatycznie. Bezpośredni import jest wymagany tylko wtedy, gdy ręcznie komponujesz łańcuch middleware Astro za pomocą `sequence(...)`.
+
+## Użycie
+
+```ts fileName="src/middleware.ts"
+import { onRequest as intlayer } from "astro-intlayer/middleware";
+import { sequence } from "astro:middleware";
+
+export const onRequest = sequence(intlayer, async (context, next) => {
+  // Dostęp do ustalonej lokalizacji w niestandardowym middleware
+  const { locale } = context.locals.intlayer;
+  console.log(`Obsługa zapytania dla lokalizacji: ${locale}`);
+
+  return next();
+});
+```
+
+## Opis
+
+Middleware wykonuje następujące operacje:
+
+1. **Wykrywanie lokalizacji**:
+   - **URL**: Analizuje prefiks ścieżki URL lub parametr zapytania `?locale=` (chyba że `routing.mode` ustawiono na `no-prefix`).
+   - **Ciasteczka / Nagłówki**: Sprawdza utrwalone ciasteczka lokalizacji lub wartości niestandardowych nagłówków.
+   - **Accept-Language**: Wykorzystuje preferencje językowe przeglądarki w przypadku braku wcześniejszych danych.
+   - Dla stron wstępnie renderowanych (`context.isPrerendered`) lokalizacja jest pobierana ściśle z adresu URL, co zapobiega ostrzeżeniom podczas budowania Astro.
+2. **Wypełnianie kontekstu**: Uzupełnia `Astro.locals.intlayer` o:
+   - `locale`: Ustaloną lokalizację.
+   - `defaultLocale`: Domyślną lokalizację rezerwową.
+   - `availableLocales`: Tablicę skonfigurowanych lokalizacji.
+3. **Zakres AsyncLocalStorage**: Obejmuje dalsze przetwarzanie zapytania zakresem `AsyncLocalStorage`, co pozwala funkcjom `useIntlayer()`, `useDictionary()` oraz `useLocale()` na dostęp do stanu zapytania bez przekazywania argumentów.
+
+## Typ `IntlayerLocals`
+
+```ts
+export type IntlayerLocals = {
+  locale: DeclaredLocales;
+  defaultLocale: DeclaredLocales;
+  availableLocales: DeclaredLocales[];
+};
+```
+
+## Powiązana dokumentacja
+
+- [Integracja `intlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/astro-intlayer/intlayer.md)
+- [Hook `useIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/astro-intlayer/useIntlayer.md)
+- [Hook `useLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/astro-intlayer/useLocale.md)

package/docs/pl/packages/astro-intlayer/useDictionary.md

@@ -0,0 +1,94 @@
+---
+createdAt: 2026-09-19
+updatedAt: 2026-09-19
+title: Dokumentacja hooka useDictionary | astro-intlayer
+description: Zobacz, jak używać hooka useDictionary w komponentach i skryptach Astro do przetwarzania obiektów słowników.
+keywords:
+  - useDictionary
+  - słownik
+  - astro
+  - astro-intlayer
+  - Intlayer
+  - intlayer
+  - Internacjonalizacja
+  - Dokumentacja
+slugs:
+  - doc
+  - packages
+  - astro-intlayer
+  - useDictionary
+history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "Inicjalizacja dokumentacji"
+author: aymericzip
+---
+
+# Dokumentacja hooka useDictionary
+
+Hook `useDictionary` przetwarza zaimportowany lub zdefiniowany w miejscu obiekt słownika i zwraca jego zawartość dla bieżącej lokalizacji w aplikacjach Astro.
+
+W przeciwieństwie do `useIntlayer`, który pobiera słowniki według klucza z globalnego rejestru słowników, `useDictionary` operuje bezpośrednio na obiekcie słownika.
+
+## Użycie
+
+```astro fileName="src/pages/index.astro"
+---
+import { useDictionary } from "astro-intlayer";
+import homeContent from "../content/home.content";
+
+const content = useDictionary(homeContent);
+---
+
+<main>
+  <h1>{content.title}</h1>
+  <p>{content.description}</p>
+</main>
+```
+
+Możesz także przekazywać słowniki zdefiniowane bezpośrednio za pomocą funkcji `t()`:
+
+```astro fileName="src/components/Footer.astro"
+---
+import { useDictionary } from "astro-intlayer";
+import { t } from "intlayer";
+
+const footer = useDictionary({
+  key: "footer",
+  content: {
+    copyright: t({
+      pl: "Wszelkie prawa zastrzeżone.",
+      en: "All rights reserved.",
+      fr: "Tous droits réservés.",
+    }),
+  },
+});
+---
+
+<footer>
+  <p>{footer.copyright}</p>
+</footer>
+```
+
+## Parametry
+
+```ts
+useDictionary(dictionary, localeOrSelector?)
+```
+
+1. **`dictionary`**: Obiekt słownika lub zakwalifikowana grupa słowników.
+2. **`localeOrSelector`** (opcjonalny): Konkretna lokalizacja lub obiekt selektora (`{ item }`, `{ variant }`, opcjonalnie z `locale`).
+
+## Opis
+
+Hook wykonuje następujące zadania:
+
+1. **Wykrywanie lokalizacji**: Na serwerze pobiera lokalizację z `Astro.locals.intlayer`. W przeglądarce korzysta z lokalizacji magazynu po stronie klienta.
+2. **Przetwarzanie treści**: Rozwiązuje tłumaczenia (`t()`), wyliczenia, warunki oraz zagnieżdżone struktury zgodnie z ustaloną lokalizacją.
+3. **Selektory**: Stosuje selektory elementów lub wariantów dostarczone w argumentach.
+
+## Powiązana dokumentacja
+
+- [Integracja `intlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/astro-intlayer/intlayer.md)
+- [Hook `useIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/astro-intlayer/useIntlayer.md)
+- [Hook `useLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/astro-intlayer/useLocale.md)

package/docs/pl/packages/astro-intlayer/useIntlayer.md

@@ -0,0 +1,98 @@
+---
+createdAt: 2026-09-19
+updatedAt: 2026-09-19
+title: Dokumentacja hooka useIntlayer | astro-intlayer
+description: Zobacz, jak używać hooka useIntlayer w komponentach Astro i skryptach klienta, aby uzyskać dostęp do zlokalizowanej treści.
+keywords:
+  - useIntlayer
+  - słownik
+  - astro
+  - astro-intlayer
+  - Intlayer
+  - intlayer
+  - Internacjonalizacja
+  - Dokumentacja
+slugs:
+  - doc
+  - packages
+  - astro-intlayer
+  - useIntlayer
+history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "Inicjalizacja dokumentacji"
+author: aymericzip
+---
+
+# Dokumentacja hooka useIntlayer
+
+Hook `useIntlayer` pozwala pobierać zlokalizowaną treść słownika na podstawie klucza w aplikacjach Astro.
+
+Może być wywoływany w dwóch różnych kontekstach za pomocą tej samej ścieżki importu:
+
+1. **Serwer / Frontmatter**: Wewnątrz plików `.astro` automatycznie ustala treść na podstawie lokalizacji zapytania zapisanej w `Astro.locals.intlayer`.
+2. **Przeglądarka / Skrypt klienta `<script>`**: Wewnątrz skryptów klienta lub komponentów frameworków UI korzysta z implementacji magazynu po stronie klienta (`vanilla-intlayer`).
+
+## Użycie
+
+### W sekcji frontmatter komponentu Astro
+
+```astro fileName="src/pages/index.astro"
+---
+import { useIntlayer } from "astro-intlayer";
+
+const content = useIntlayer("home");
+---
+
+<main>
+  <h1>{content.title}</h1>
+  <p>{content.description}</p>
+</main>
+```
+
+### W blokach `<script>` klienta
+
+```astro fileName="src/components/InteractiveWidget.astro"
+---
+import { useIntlayer } from "astro-intlayer";
+
+const content = useIntlayer("home");
+---
+
+<button id="alert-btn">{content.buttonText}</button>
+
+<script>
+  import { useIntlayer } from "astro-intlayer";
+
+  const content = useIntlayer("home");
+
+  document.getElementById("alert-btn")?.addEventListener("click", () => {
+    alert(content.buttonText);
+  });
+</script>
+```
+
+## Parametry
+
+```ts
+useIntlayer(key, localeOrSelector?)
+```
+
+1. **`key`**: Unikalny klucz słownika (zgodnie z definicją w plikach deklaracji `.content.ts`).
+2. **`localeOrSelector`** (opcjonalny): Konkretna lokalizacja lub obiekt selektora (`{ item }`, `{ variant }`, opcjonalnie z `locale`). Gdy zostanie podany, nadpisuje lokalizację wykrytą z kontekstu zapytania lub magazynu klienta.
+
+## Opis
+
+Hook wykonuje następujące zadania:
+
+1. **Ustalanie lokalizacji**:
+   - Na serwerze odczytuje aktywną lokalizację z `Astro.locals.intlayer` za pośrednictwem zakresu `AsyncLocalStorage` zainicjowanego przez `astro-intlayer/middleware`.
+   - W przeglądarce odczytuje aktywną lokalizację z magazynu klienta.
+2. **Pobieranie słownika**: Wstrzykuje zawartość słownika pasującą do określonego klucza.
+3. **Przetwarzanie tłumaczeń**: Rozwiązuje tłumaczenia (`t()`), wyliczenia, warunki i markdown na gotową do wyświetlenia treść.
+
+## Powiązana dokumentacja
+
+- [Integracja `intlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/astro-intlayer/intlayer.md)
+- [Hook `useDictionary`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/astro-intlayer/useDictionary.md)
+- [Hook `useLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/astro-intlayer/useLocale.md)

package/docs/pl/packages/astro-intlayer/useLocale.md

@@ -0,0 +1,126 @@
+---
+createdAt: 2026-09-19
+updatedAt: 2026-09-19
+title: Dokumentacja hooka useLocale | astro-intlayer
+description: Zobacz, jak używać hooka useLocale w aplikacjach Astro, aby uzyskać dostęp do bieżącej lokalizacji i zarządzać nią.
+keywords:
+  - useLocale
+  - locale
+  - astro
+  - astro-intlayer
+  - Intlayer
+  - intlayer
+  - Internacjonalizacja
+  - Dokumentacja
+slugs:
+  - doc
+  - packages
+  - astro-intlayer
+  - useLocale
+history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "Inicjalizacja dokumentacji"
+author: aymericzip
+---
+
+# Dokumentacja hooka useLocale
+
+Hook `useLocale` z pakietu `astro-intlayer` zapewnia dostęp do aktualnej lokalizacji zapytania, skonfigurowanej domyślnej lokalizacji oraz wszystkich dostępnych lokalizacji w aplikacjach Astro.
+
+Działa spójnie zarówno w sekcji frontmatter komponentów `.astro` renderowanych na serwerze, jak i w blokach skryptów klienta `<script>`.
+
+## Użycie
+
+### W sekcji frontmatter komponentu (renderowanie na serwerze)
+
+```astro fileName="src/layouts/Layout.astro"
+---
+import { useLocale } from "astro-intlayer";
+import { getLocalizedUrl, getPathWithoutLocale } from "intlayer";
+
+const { locale, defaultLocale, availableLocales } = useLocale();
+const pathWithoutLocale = getPathWithoutLocale(Astro.url.pathname);
+---
+
+<!DOCTYPE html>
+<html lang={locale}>
+  <head>
+    <meta charset="utf-8" />
+    <title>Astro + Intlayer</title>
+  </head>
+  <body>
+    <header>
+      <span>Bieżący: {locale}</span>
+      <span>Domyślny: {defaultLocale}</span>
+      <nav>
+        <ul>
+          {availableLocales.map((localeItem) => (
+            <li key={localeItem} className="p-1">
+              <a
+                href={getLocalizedUrl(pathWithoutLocale, localeItem)}
+                aria-current={localeItem === locale ? "page" : undefined}
+              >
+                {localeItem.toUpperCase()}
+              </a>
+            </li>
+          ))}
+        </ul>
+      </nav>
+    </header>
+    <slot />
+  </body>
+</html>
+```
+
+### W skrypcie klienta `<script>` (interaktywność)
+
+```astro fileName="src/components/LocaleSwitcher.astro"
+---
+import { useLocale } from "astro-intlayer";
+
+const { locale, availableLocales } = useLocale();
+---
+
+<select id="locale-select">
+  {availableLocales.map((loc) => (
+    <option value={loc} selected={loc === locale}>
+      {loc.toUpperCase()}
+    </option>
+  ))}
+</select>
+
+<script>
+  import { useLocale, setLocaleInStorage } from "astro-intlayer";
+
+  const { setLocale } = useLocale();
+
+  document.getElementById("locale-select")?.addEventListener("change", (e) => {
+    const target = e.target as HTMLSelectElement;
+    setLocale(target.value);
+  });
+</script>
+```
+
+## Zwracane wartości
+
+Hook zwraca obiekt typu `UseLocaleResult`:
+
+| Właściwość         | Typ                                    | Opis                                                                                                         |
+| ------------------ | -------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `locale`           | `DeclaredLocales`                      | Aktywna lokalizacja.                                                                                         |
+| `defaultLocale`    | `DeclaredLocales`                      | Domyślna lokalizacja rezerwowa skonfigurowana w `intlayer.config.ts`.                                        |
+| `availableLocales` | `DeclaredLocales[]`                    | Tablica wszystkich obsługiwanych lokalizacji skonfigurowanych w projekcie.                                   |
+| `setLocale`        | `(locale: LocalesValues) => void`      | Funkcja do aktualizacji lokalizacji. (Interaktywna w `<script>` klienta, wyświetla ostrzeżenie podczas SSR). |
+| `subscribe`        | `(callback: () => void) => () => void` | Subskrybuje zmiany lokalizacji po stronie klienta.                                                           |
+
+## Zachowanie na serwerze a na kliencie
+
+- **Podczas SSR / renderowania na serwerze**: Zapytanie jest renderowane jednokrotnie ze stałymi parametrami. Wywołanie `setLocale()` podczas renderowania na serwerze nie przynosi efektu i generuje ostrzeżenie; przełączanie lokalizacji powinno odbywać się po stronie klienta lub poprzez przejście pod adres URL z odpowiednią lokalizacją.
+- **W skryptach klienta**: `setLocale` aktualizuje magazyn klienta oraz zapisane ciasteczka lub pamięć lokalną zgodnie z konfiguracją Intlayer.
+
+## Powiązana dokumentacja
+
+- [Integracja `intlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/astro-intlayer/intlayer.md)
+- [Hook `useIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/astro-intlayer/useIntlayer.md)
+- [Hook `useDictionary`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/astro-intlayer/useDictionary.md)