@intlayer/docs 9.3.3 → 9.4.0

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

@@ -0,0 +1,136 @@
+---
+createdAt: 2026-08-24
+updatedAt: 2026-08-24
+title: Dokumentacja pakietu elysia-intlayer
+description: Wtyczka Elysia dla Intlayer, zapewniająca funkcje tłumaczeń i wykrywanie locale.
+keywords:
+  - elysia-intlayer
+  - elysia
+  - plugin
+  - internationalization
+  - i18n
+slugs:
+  - doc
+  - packages
+  - elysia-intlayer
+  - exports
+history:
+  - version: 9.4.0
+    date: 2026-08-24
+    changes: "Ujednolicona dokumentacja dla wszystkich eksportów"
+author: aymericzip
+---
+
+# Pakiet elysia-intlayer
+
+Pakiet `elysia-intlayer` udostępnia wtyczkę dla aplikacji Elysia do obsługi internationalization (i18n). Wykrywa locale użytkownika i wstrzykuje obiekt `intlayer` do kontekstu route.
+
+## Instalacja
+
+```bash packageManager="npm"
+npm install intlayer elysia-intlayer
+```
+
+```bash packageManager="pnpm"
+pnpm add intlayer elysia-intlayer
+```
+
+```bash packageManager="yarn"
+yarn add intlayer elysia-intlayer
+```
+
+```bash packageManager="bun"
+bun add intlayer elysia-intlayer
+```
+
+> `elysia` jest peer dependency (`>=1.0.0`). Elysia jest przeznaczony dla runtime **Bun**.
+
+## Eksporty
+
+### Wtyczka
+
+Import:
+
+```ts
+import { intlayer } from "elysia-intlayer";
+```
+
+| Funkcja    | Opis                                                                                                                                                                                                                                                                                                                           | Powiązana dokumentacja                                                                                         |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
+| `intlayer` | Wtyczka Elysia integrująca Intlayer z Twoją aplikacją Elysia. Obsługuje wykrywanie locale ze storage (cookies, headers), a następnie z `Accept-Language`, wstrzykuje obiekt `intlayer` udostępniający `locale`, `t`, `getIntlayer` i `getDictionary` do kontekstu route oraz konfiguruje kontekst żądania `AsyncLocalStorage`. | [intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/elysia-intlayer/intlayer.md) |
+
+### Funkcje
+
+Import:
+
+```ts
+import { t, getIntlayer, getDictionary } from "elysia-intlayer";
+```
+
+| Funkcja         | Opis                                                                                                                                                                                                                                                                    | Powiązana dokumentacja                                                                                 |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `t`             | Globalna funkcja tłumaczenia pobierająca treść dla bieżącego locale w Elysia. Używa `AsyncLocalStorage`, aby uzyskać dostęp do kontekstu żądania skonfigurowanego przez wtyczkę `intlayer`, a poza nim wraca do domyślnego locale. Dostępna również przez `intlayer.t`. | [translation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/dictionary/translation.md) |
+| `getIntlayer`   | Pobiera słownik po kluczu z wygenerowanej deklaracji i zwraca jego treść dla bieżącego locale. Zoptymalizowana wersja `getDictionary`. Używa `AsyncLocalStorage`, aby uzyskać dostęp do kontekstu żądania. Dostępna również przez `intlayer.getIntlayer`.               | -                                                                                                      |
+| `getDictionary` | Przetwarza obiekty słowników i zwraca treść dla bieżącego locale. Przetwarza tłumaczenia `t()`, enumeracje, markdown, HTML itd. Używa `AsyncLocalStorage`, aby uzyskać dostęp do kontekstu żądania. Dostępna również przez `intlayer.getDictionary`.                    | -                                                                                                      |
+
+### Typy
+
+Import:
+
+```ts
+import type { IntlayerContext, TranslateFunction } from "elysia-intlayer";
+```
+
+| Typ                 | Opis                                                                                                                                                                       |
+| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `IntlayerContext`   | Kształt obiektu `intlayer` wstrzykiwanego do każdego kontekstu route: `locale`, `locale_storage`, `locale_detected`, `defaultLocale`, `t`, `getIntlayer`, `getDictionary`. |
+| `TranslateFunction` | Sygnatura funkcji tłumaczenia, przekształcającej locale map w treść odpowiadającą locale bieżącego żądania.                                                                |
+
+## Użycie
+
+```ts fileName="src/index.ts"
+import { Elysia } from "elysia";
+import { getDictionary, getIntlayer, intlayer, t } from "elysia-intlayer";
+import dictionaryExample from "./index.content";
+
+const app = new Elysia()
+  // Załaduj wtyczkę internacjonalizacji
+  .use(intlayer())
+  // Odczytaj locale i helpery z kontekstu trasy
+  .get("/", ({ intlayer }) => ({
+    locale: intlayer!.locale,
+    greeting: intlayer!.t({
+      pl: "Cześć",
+      en: "Hello",
+      fr: "Bonjour",
+      es: "Hola",
+    }),
+    content: intlayer!.getIntlayer("index").exampleOfContent,
+  }))
+  // Albo użyj samodzielnych helperów, powiązanych z bieżącym żądaniem
+  .get("/t_example", () =>
+    t({
+      pl: "Przykład zwróconej treści w języku polskim",
+      en: "Example of returned content in English",
+      fr: "Exemple de contenu renvoyé en français",
+      es: "Ejemplo de contenido devuelto en español",
+    })
+  )
+  .get("/getIntlayer_example", () => getIntlayer("index").exampleOfContent)
+  .get(
+    "/getDictionary_example",
+    () => getDictionary(dictionaryExample).exampleOfContent
+  )
+  .listen(3000);
+
+console.log(
+  `🦊 Elysia is running at ${app.server?.hostname}:${app.server?.port}`
+);
+```
+
+> Plugin rejestruje swój kontekst poprzez **globalny** `derive`, który Elysia typuje jako `Partial<{ intlayer: IntlayerContext }>`. W czasie działania wartość jest zawsze obecna dla tras zarejestrowanych po `.use(intlayer())`, dlatego użyj non-null assertion (`intlayer!.locale`) — lub optional chaining — aby zadowolić TypeScript w trybie `strict`.
+
+## Powiązana dokumentacja
+
+- [Elysia i18n - Kompletny przewodnik tłumaczenia aplikacji](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/intlayer_with_elysia.md)
+- [Konfiguracja](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/configuration.md)

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

@@ -0,0 +1,139 @@
+---
+createdAt: 2026-08-24
+updatedAt: 2026-08-24
+title: Dokumentacja wtyczki intlayer dla Elysia | elysia-intlayer
+description: Zobacz, jak używać wtyczki intlayer z pakietu elysia-intlayer
+keywords:
+  - intlayer
+  - elysia
+  - plugin
+  - Intlayer
+  - Internacjonalizacja
+  - Dokumentacja
+slugs:
+  - doc
+  - packages
+  - elysia-intlayer
+  - intlayer
+history:
+  - version: 9.4.0
+    date: 2026-08-24
+    changes: "Inicjalizacja dokumentacji"
+author: aymericzip
+---
+
+# Dokumentacja wtyczki intlayer dla Elysia
+
+Wtyczka `intlayer` dla Elysia wykrywa locale użytkownika i wstrzykuje obiekt `intlayer` do kontekstu route. Umożliwia również użycie globalnych funkcji tłumaczeniowych w kontekście żądania.
+
+## Użycie
+
+```ts fileName="src/index.ts"
+import { Elysia } from "elysia";
+import { intlayer } from "elysia-intlayer";
+
+const app = new Elysia().use(intlayer()).get("/", ({ intlayer }) =>
+  intlayer!.t({
+    pl: "Cześć",
+    en: "Hello",
+    fr: "Bonjour",
+    es: "Hola",
+  })
+);
+```
+
+> Plugin rejestruje swój kontekst poprzez **globalny** `derive`, który Elysia typuje jako `Partial<{ intlayer: IntlayerContext }>`. W czasie działania wartość jest zawsze obecna dla tras zarejestrowanych po `.use(intlayer())`, dlatego użyj non-null assertion (`intlayer!.t`) — lub optional chaining — aby zadowolić TypeScript w trybie `strict`.
+
+Te same helpery są dostępne jako samodzielne eksporty, więc możesz je wywołać bez destrukturyzacji kontekstu route:
+
+```ts fileName="src/index.ts"
+import { Elysia } from "elysia";
+import { intlayer, t } from "elysia-intlayer";
+
+const app = new Elysia().use(intlayer()).get("/", () =>
+  t({
+    pl: "Cześć",
+    en: "Hello",
+    fr: "Bonjour",
+    es: "Hola",
+  })
+);
+```
+
+## Opis
+
+Wtyczka wykonuje następujące zadania:
+
+1. **Wykrywanie locale**: Odczytuje locale ustawione jawnie przez klienta ze storage (cookie, header), a następnie wraca do locale wynegocjowanego z nagłówka `Accept-Language`.
+2. **Wstrzyknięcie do kontekstu**: Dodaje właściwość `intlayer` do kontekstu trasy Elysia (zobacz tabelę Kontekst trasy poniżej).
+3. **Zarządzanie kontekstem**: Używa `AsyncLocalStorage` do zarządzania asynchronicznym kontekstem, dzięki czemu globalne funkcje Intlayer (`t`, `getIntlayer`, `getDictionary`) mają dostęp do locale specyficznego dla żądania bez przekazywania obiektu kontekstu.
+4. **Przygotowanie słowników**: Wywołuje `prepareIntlayer` przy tworzeniu pluginu, dzięki czemu słowniki są budowane przy starcie aplikacji.
+
+### Kontekst trasy
+
+| Właściwość        | Typ                    | Opis                                                                                                  |
+| ----------------- | ---------------------- | ----------------------------------------------------------------------------------------------------- |
+| `locale`          | `Locale`               | Locale używane dla tego żądania, przy czym `locale_storage` ma pierwszeństwo przed `locale_detected`. |
+| `locale_storage`  | `Locale` (opcjonalne)  | Locale zażądane jawnie przez klienta poprzez cookie lub header.                                       |
+| `locale_detected` | `Locale`               | Locale wynegocjowane z nagłówków żądania.                                                             |
+| `defaultLocale`   | `Locale`               | Locale skonfigurowane jako fallback w `intlayer.config.ts`.                                           |
+| `t`               | `TranslateFunction`    | Funkcja tłumaczenia.                                                                                  |
+| `getIntlayer`     | `typeof getIntlayer`   | Funkcja pobierająca słowniki po kluczu.                                                               |
+| `getDictionary`   | `typeof getDictionary` | Funkcja przetwarzająca obiekty słowników.                                                             |
+
+> W przeciwieństwie do wtyczek Intlayer opartych na Node, `elysia-intlayer` opiera się na `AsyncLocalStorage` zamiast `cls-hooked`, ponieważ `cls-hooked` zależy od `async_hooks.createHook`, którego Bun nie implementuje.
+
+Kontekst żądania jest zwalniany po zmapowaniu odpowiedzi, więc samodzielne helpery nigdy nie rozwiązują się względem już zakończonego żądania. Wywołane poza żądaniem obsługiwanym przez wtyczkę, wracają do skonfigurowanego domyślnego locale.
+
+## Kolejność rozwiązywania locale
+
+Domyślnie plugin rozwiązuje locale w następującej kolejności:
+
+1. Cookie `INTLAYER_LOCALE`.
+2. Nagłówek `x-intlayer-locale`.
+3. Negocjacja nagłówka `Accept-Language`.
+4. Skonfigurowany `defaultLocale`.
+
+```bash
+# Wynegocjowany z `Accept-Language`
+curl -H "Accept-Language: fr" http://localhost:3000/
+# Bonjour
+
+# Cookie ma pierwszeństwo przed `Accept-Language`
+curl -H "Accept-Language: fr" -H "Cookie: INTLAYER_LOCALE=es" http://localhost:3000/
+# Hola
+
+# Nagłówek ma pierwszeństwo przed `Accept-Language`
+curl -H "Accept-Language: fr" -H "x-intlayer-locale: es" http://localhost:3000/
+# Hola
+```
+
+## Konfiguracja
+
+Wtyczka odczytuje Twój plik `intlayer.config.ts`. Możesz dostosować cookie i header używane do wykrywania locale:
+
+```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  routing: {
+    storage: [
+      { type: "header", name: "my-locale-header" },
+      { type: "cookie", name: "my-locale-cookie" },
+    ],
+  },
+};
+
+export default config;
+```
+
+> Więcej informacji o konfiguracji znajdziesz w [dokumentacji konfiguracji](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/configuration.md).
+
+## Powiązana dokumentacja
+
+- [Dokumentacja pakietu elysia-intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/elysia-intlayer/exports.md)
+- [Elysia i18n - Kompletny przewodnik tłumaczenia aplikacji](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/intlayer_with_elysia.md)

package/docs/pl/packages/intlayer/getDictionary.md

@@ -0,0 +1,154 @@
+---
+createdAt: 2026-08-23
+updatedAt: 2026-08-23
+title: Dokumentacja funkcji getDictionary | intlayer
+description: Zobacz, jak używać funkcji getDictionary dla pakietu intlayer
+keywords:
+  - getDictionary
+  - dictionary
+  - interpreter
+  - content
+  - Intlayer
+  - intlayer
+  - Internationalization
+  - Documentation
+  - JavaScript
+  - TypeScript
+slugs:
+  - doc
+  - packages
+  - intlayer
+  - getDictionary
+history:
+  - version: 9.4.0
+    date: 2026-08-23
+    changes: "Initial documentation"
+author: aymericzip
+---
+
+# Dokumentacja: Funkcja `getDictionary` w `intlayer`
+
+## Opis
+
+Funkcja `getDictionary` interpretuje obiekt słownika **który sam przekazujesz** i zwraca jego rozwiązaną treść dla danego locale'a. Przechodzi przez treść w jednym przejściu i stosuje każdą wtyczkę interpretera w razie potrzeby, rozwiązując tłumaczenia `t()`, wyliczenia, warunki, wstawienia, zagnieżdżenia, markdown, HTML i węzły plików.
+
+W przeciwieństwie do [`getIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/intlayer/getIntlayer.md), która wyszukuje słownik według klucza w wygenerowanym rejestrze, `getDictionary` przyjmuje sam słownik. To czyni go właściwym narzędziem dla treści zbudowanej w czasie działania, pobieranej z API lub CMS, lub zadeklarowanej inline w teście.
+
+**Kluczowe cechy:**
+
+- Działa z dowolnym obiektem zgodnym ze strukturą słownika (`{ key, content }`)
+- Przyjmuje również kwalifikowaną grupę słownika (kolekcje, warianty) wraz z selektorem
+- W pełni typizowane: zwrócony obiekt odzwierciedla `content`, który przekazałeś
+- Akceptuje niestandardowe wtyczki interpretera
+
+---
+
+## Sygnatura funkcji
+
+```typescript
+getDictionary(
+  dictionary: Dictionary | QualifiedDictionaryGroup, // Wymagane
+  localeOrSelector?: LocalesValues | DictionarySelector, // Opcjonalne
+  plugins?: Plugins[]                                // Opcjonalne
+): DeepTransformContent<...>
+```
+
+---
+
+## Parametry
+
+- `dictionary: Dictionary | QualifiedDictionaryGroup`
+  - **Description**: Słownik (lub kvalifikowana grupa słowników) do interpretacji.
+  - **Type**: `Dictionary | QualifiedDictionaryGroup`
+  - **Required**: Yes
+
+- `localeOrSelector: LocalesValues | DictionarySelector`
+  - **Description**: Język (locale) do interpretacji zawartości, lub obiekt selektora (`{ item }`, `{ variant }`, opcjonalnie z `locale`). Zobacz [dynamic dictionaries](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/dynamic_dictionaries/index.md).
+  - **Type**: `LocalesValues | DictionarySelector`
+  - **Required**: No (Optional) — defaults to the configured `defaultLocale`.
+
+- `plugins: Plugins[]`
+  - **Description**: Tablica transformatorów węzłów definiująca sposób interpretacji rozpoznanych węzłów. Jeśli zostanie pominięta, używany jest domyślny zestaw wtyczek interpretera.
+  - **Type**: `Plugins[]`
+  - **Required**: No (Optional)
+
+### Zwraca
+
+- **Typ**: Interpretowana zawartość słownika.
+- **Opis**: `content` które przekazałeś, ze wszystkimi węzłami Intlayer rozwiązanymi dla żądanego ustawienia regionu. Dla grupy kolekcji bez selektora `item`, zwracana jest posortowana tablica interpretowanych wpisów; `null` jest zwracane, gdy selektor nie wskazuje na nic.
+
+---
+
+## Przykład użycia
+
+### Podstawowe użycie
+
+```typescript codeFormat={["typescript", "esm", "commonjs"]}
+import { getDictionary, t } from "intlayer";
+
+const content = getDictionary(
+  {
+    key: "my_key",
+    content: {
+      greeting: t({
+        en: "Hello",
+        fr: "Bonjour",
+      }),
+    },
+  },
+  "fr"
+);
+
+console.log(content.greeting); // "Bonjour"
+```
+
+### Interpretowanie zawartości pobranej w czasie wykonywania
+
+```typescript
+import { getDictionary, type Dictionary } from "intlayer";
+
+const remoteDictionary: Dictionary = await fetch("/api/cms/banner").then(
+  (res) => res.json()
+);
+
+const banner = getDictionary(remoteDictionary, "fr");
+```
+
+### Z selektorem
+
+```typescript
+import { getDictionary } from "intlayer";
+
+// Kwalifikowana grupa słownika jest rozwiązywana do pojedynczego wpisu…
+const secondItem = getDictionary(blogPostGroup, { item: 2, locale: "fr" });
+
+// …lub do uporządkowanej tablicy, gdy `item` nie jest podany
+const allItems = getDictionary(blogPostGroup, { locale: "fr" });
+```
+
+---
+
+## Powiązane funkcje
+
+- [`getIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/intlayer/getIntlayer.md): Ta sama interpretacja, ale słownik jest wyszukiwany po kluczu w wygenerowanym rejestrze.
+- [`getDictionaryAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/intlayer/getDictionaryAsync.md): Odpowiednik dla map loaderów dla każdej lokalizacji.
+- [`useDictionary`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/react-intlayer/useDictionary.md): Odpowiednik React hook, odczytujący lokalizację od dostawcy.
+
+---
+
+## TypeScript
+
+```typescript
+function getDictionary<
+  const T extends Dictionary | QualifiedDictionaryGroup,
+  const A extends LocalesValues | DictionarySelector = DeclaredLocales,
+>(
+  dictionary: T,
+  localeOrSelector?: A,
+  plugins?: Plugins[]
+): DeepTransformContent<
+  ResolveQualifiedDictionaryContent<T, A>,
+  IInterpreterPluginState,
+  ExtractSelectorLocale<A>
+>;
+```

package/docs/pl/packages/intlayer/getDictionaryAsync.md

@@ -0,0 +1,166 @@
+---
+createdAt: 2026-08-23
+updatedAt: 2026-08-23
+title: Dokumentacja funkcji getDictionaryAsync | intlayer
+description: Sprawdź, jak używać funkcji getDictionaryAsync dla pakietu intlayer
+keywords:
+  - getDictionaryAsync
+  - dictionary
+  - dynamic dictionaries
+  - loader map
+  - bundle optimization
+  - Intlayer
+  - intlayer
+  - Internationalization
+  - Documentation
+  - JavaScript
+  - TypeScript
+slugs:
+  - doc
+  - packages
+  - intlayer
+  - getDictionaryAsync
+history:
+  - version: 9.4.0
+    date: 2026-08-23
+    changes: "Initial documentation"
+author: aymericzip
+---
+
+# Dokumentacja: funkcja `getDictionaryAsync` w `intlayer`
+
+## Opis
+
+Funkcja `getDictionaryAsync` ładuje **pojedynczy chunk ustawień regionalnych** ze słownika i zwraca jego interpretowaną zawartość.
+
+Jest to odpowiednik [`getDictionary`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/intlayer/getDictionary.md) dla map loaderów na ustawienia regionalne emitowanych w `.intlayer/dynamic_dictionaries/`: zamiast otrzymywać słownik zawierający wszystkie ustawienia regionalne, otrzymuje mapę loadera i czeka tylko na chunk potrzebny dla żądanych ustawień regionalnych.
+
+> W kodzie aplikacji zazwyczaj wywołujesz [`getIntlayerAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/intlayer/getIntlayerAsync.md), a nie tę funkcję. [Pluginy build](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/bundle_optimization.md) przepisują każde wywołanie `getIntlayerAsync('key', locale)` na `getDictionaryAsync(loaderMap, 'key', locale)`. `getDictionaryAsync` jest eksportowana dla niestandardowych loaderów i narzędzi, które budują własne mapy loaderów.
+
+**Kluczowe funkcje:**
+
+- Ładuje tylko żądany chunk ustawień regionalnych
+- Obsługuje proste (`locale → loader`) i kwalifikowane (`locale → qualifierId → loader`) mapy loaderów
+- Deduplikuje jednoczesne ładowania tego samego chunku i cache'uje rozwiązaną zawartość
+- Nieudane ładowania są usuwane z cache'u, aby późniejsze wywołanie ponowiło próbę chunku
+
+---
+
+## Sygnatura funkcji
+
+```typescript
+getDictionaryAsync(
+  dictionaryLoaders: PlainDynamicLoaderMap | QualifiedDynamicLoaderMap, // Wymagane
+  key: string,                                           // Wymagane
+  localeOrSelector?: LocalesValues | DictionarySelector, // Opcjonalne
+  plugins?: Plugins[]                                    // Opcjonalne
+): Promise<DeepTransformContent<...>>
+```
+
+---
+
+## Parametry
+
+- `dictionaryLoaders: PlainDynamicLoaderMap | QualifiedDynamicLoaderMap`
+  - **Description**: Mapa loaderów dla każdej lokalizacji. Mapy zwykłe powiązują lokalizację z loaderem; mapy kwalifikowane (używane przez kolekcje i warianty) powiązują lokalizację z identyfikatorem kwalifikatora, a następnie z loaderem. Dla mapy kwalifikowanej ładowane są tylko fragmenty, na które wskazuje selektor.
+  - **Type**: `PlainDynamicLoaderMap<T> | QualifiedDynamicLoaderMap`
+  - **Required**: Yes
+
+- `key: string`
+  - **Description**: Klucz słownika, używany do namespacing cache'u fragmentów.
+  - **Type**: `string`
+  - **Required**: Yes
+
+- `localeOrSelector: LocalesValues | DictionarySelector`
+  - **Description**: Lokalizacja do interpretacji zawartości lub obiekt selektora (`{ item }`, `{ variant }`, opcjonalnie z `locale`). Patrz [dynamiczne słowniki](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/dynamic_dictionaries/index.md).
+  - **Type**: `LocalesValues | DictionarySelector`
+  - **Required**: No (Optional) — defaults to the configured `defaultLocale`.
+
+- `plugins: Plugins[]`
+  - **Description**: Transformatory węzłów. Domyślnie ustawiony na bazowy zestaw interpretera.
+  - **Type**: `Plugins[]`
+  - **Required**: No (Optional)
+
+### Returns
+
+- **Type**: `Promise<Content>` — obietnica rozwiązująca się do interpretowanej zawartości załadowanego fragmentu.
+- **Description**: Rozwiązuje się do `null`, gdy mapa nie emituje żadnego fragmentu dla żądanej lokalizacji ani żadnych jej fallbacków, odzwierciedlając sposób, w jaki rozwiązuje się brakująca kwalifikowana współrzędna.
+
+---
+
+## Przykładowe użycie
+
+### Z wygenerowaną mapą ładowarki
+
+```typescript codeFormat={["typescript", "esm", "commonjs"]}
+import { getDictionaryAsync } from "intlayer";
+import appLoaderMap from "../.intlayer/dynamic_dictionaries/app";
+
+const { title } = await getDictionaryAsync(appLoaderMap, "app", "fr");
+```
+
+### Z niestandardową mapą loadera
+
+```typescript
+import { getDictionaryAsync } from "intlayer";
+
+const loaderMap = {
+  en: () => import("./banner.en.json").then((mod) => mod.default),
+  fr: () => import("./banner.fr.json").then((mod) => mod.default),
+};
+
+const banner = await getDictionaryAsync(loaderMap, "banner", "fr");
+```
+
+### Z selectorem na mapie kwalifikowanej
+
+```typescript
+import { getDictionaryAsync } from "intlayer";
+
+const promoBanner = await getDictionaryAsync(bannerLoaderMap, "banner", {
+  variant: "black-friday",
+  locale: "fr",
+});
+```
+
+---
+
+## Uwagi dotyczące zachowania
+
+### Buforowanie i deduplikacja
+
+Pamięć podręczna przechowuje **promise** każdej trójki `key + locale + selector`, dzięki czemu równoczesne wywołania dla tego samego fragmentu czekają na jedno załadowanie. Odrzucone załadowanie jest usuwane z pamięci podręcznej, więc fragment, który się nie powiedzie, jest ponownie próbowany przy następnym wywołaniu zamiast powtarzania tego samego błędu w nieskończoność.
+
+### Fallback ustawień regionalnych
+
+Zwykła mapa loaderów jest przechodzana wzdłuż tego samego łańcucha fallback co w trybie synchronicznym: najpierw żądane ustawienie regionalne, następnie jego fallbacki, a następnie `null` jeśli żaden nie emitował chunk'u.
+
+---
+
+## Powiązane funkcje
+
+- [`getIntlayerAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/intlayer/getIntlayerAsync.md): Funkcja wywoływana przez aplikacje; wtyczki build przepisują ją na `getDictionaryAsync`.
+- [`getDictionary`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/intlayer/getDictionary.md): Synchroniczny odpowiednik przyjmujący pełny słownik.
+- [Dynamiczne słowniki](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/dynamic_dictionaries/index.md): Kolekcje i warianty, oraz mapy loaderów które generują.
+
+---
+
+## TypeScript
+
+```typescript
+function getDictionaryAsync<
+  const T extends Dictionary,
+  const A extends LocalesValues | DictionarySelector = DeclaredLocales,
+>(
+  dictionaryLoaders: PlainDynamicLoaderMap<T> | QualifiedDynamicLoaderMap,
+  key: string,
+  localeOrSelector?: A,
+  plugins?: Plugins[]
+): Promise<
+  DeepTransformContent<
+    T["content"],
+    IInterpreterPluginState,
+    ExtractSelectorLocale<A>
+  >
+>;
+```

package/docs/pl/packages/intlayer/getEnumeration.md

@@ -31,6 +31,8 @@ author: aymericzip
 
 Funkcja `getEnumeration` pobiera zawartość odpowiadającą określonej ilości na podstawie zdefiniowanych warunków w obiekcie enumeracji. Warunki są zdefiniowane jako klucze, a ich priorytet jest określany przez kolejność w obiekcie.
 
+Aby uzyskać więcej szczegółów na temat deklarowania wyliczeń, zobacz [dokumentację Enumeration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/dictionary/enumeration.md).
+
 ## Parametry
 
 - `enumerationContent: QuantityContent<Content>`