@intlayer/docs 9.4.0-canary.0 → 9.4.0

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>`

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

@@ -0,0 +1,197 @@
+---
+createdAt: 2026-08-23
+updatedAt: 2026-08-23
+title: Dokumentacja funkcji getIntlayer | intlayer
+description: Zobacz jak używać funkcji getIntlayer dla pakietu intlayer
+keywords:
+  - getIntlayer
+  - dictionary
+  - content
+  - selector
+  - Intlayer
+  - intlayer
+  - Internationalization
+  - Documentation
+  - JavaScript
+  - TypeScript
+slugs:
+  - doc
+  - packages
+  - intlayer
+  - getIntlayer
+history:
+  - version: 9.4.0
+    date: 2026-08-23
+    changes: "Dokumentacja początkowa"
+author: aymericzip
+---
+
+# Dokumentacja: Funkcja `getIntlayer` w `intlayer`
+
+## Opis
+
+Funkcja `getIntlayer` wybiera jeden słownik po jego kluczu i zwraca jego zawartość zinterpretowaną dla danego ustawienia regionalne. Jest to odpowiednik niezależny od frameworka hooka `useIntlayer`: ta sama zawartość, te same selektory, ale możliwy do użycia wszędzie tam, gdzie kontekst React nie jest dostępny — skrypty Node, funkcje serwera, loadery tras, budowniczy metadanych, handlery Express/Fastify, testy.
+
+Odczytuje słowniki wygenerowane przez Intlayer w `.intlayer/`, więc argument `key` jest typowany i autocomplete'owany z Twoich własnych deklaracji zawartości, a zwrócony obiekt jest w pełni typowany do każdego liścia.
+
+**Kluczowe funkcje:**
+
+- Typowane klucze słownika i typowana zwrócona zawartość
+- Interpretuje każdy węzeł zawartości (`t()`, `enu()`, `cond()`, `insert()`, `nest()`, `md()`, `html()`, `file()`, `gender()`)
+- Akceptuje ustawienie regionalne lub obiekt selektora (kolekcje, warianty)
+- Wyniki są zapamiętywane dla `key + locale + selector`
+- Spada do bezpiecznego proxy w trybie development, gdy słownik brakuje, zamiast się wysypać
+
+---
+
+## Sygnatura funkcji
+
+```typescript
+getIntlayer(
+  key: DictionaryKeys,                        // Wymagane
+  localeOrSelector?: LocalesValues | DictionarySelector, // Opcjonalne
+  plugins?: Plugins[]                         // Opcjonalne
+): DeepTransformContent<...>
+```
+
+---
+
+## Parametry
+
+- `key: DictionaryKeys`
+  - **Description**: Klucz słownika do odczytania, zadeklarowany w plikach zawartości.
+  - **Type**: `DictionaryKeys` — suma wszystkich zadeklarowanych kluczy słownika.
+  - **Required**: Yes
+
+- `localeOrSelector: LocalesValues | DictionarySelector`
+  - **Description**: Locale do interpretacji zawartości lub obiekt selektora dla [dynamicznych słowników](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/dynamic_dictionaries/index.md).
+    - `'fr'` — locale
+    - `{ item: 2 }` — element [kolekcji](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/dynamic_dictionaries/collections.md) (pomiń `item`, aby uzyskać każdy element jako tablicę)
+    - `{ variant: 'black-friday' }` — nazwana [wariacja](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/dynamic_dictionaries/variants.md) (pomiń dla domyślnej)
+    - `{ variant: { id: 'prod_abc', userId: '123' } }` — wariacja strukturalna
+    - Każdy selektor może zawierać locale: `{ item: 2, locale: 'fr' }`
+  - **Type**: `LocalesValues | DictionarySelector`
+  - **Required**: No (Optional) — domyślnie do skonfigurowanego `defaultLocale`.
+
+- `plugins: Plugins[]`
+  - **Description**: Niestandardowe transformery węzłów zastępujące bazowe pluginy interpretera. Zaawansowane użycie; pomiń, aby zachować domyślne zachowanie.
+  - **Type**: `Plugins[]`
+  - **Required**: No (Optional)
+
+### Zwracane wartości
+
+- **Type**: Zinterpretowana zawartość słownika, wpisana na podstawie Twojej deklaracji.
+- **Description**: Zwykły obiekt odzwierciedlający pole `content` słownika, gdzie każdy węzeł Intlayer został rozwiązany do jego ostatecznej wartości dla żądanego ustawienia regionalne.
+
+---
+
+## Przykład użycia
+
+### Podstawowe użycie
+
+```typescript fileName="src/app.content.ts" codeFormat="typescript"
+import { t, type Dictionary } from "intlayer";
+
+const appContent = {
+  key: "app",
+  content: {
+    title: t({
+      pl: "Cześć",
+      en: "Hello",
+      fr: "Bonjour",
+    }),
+  },
+} satisfies Dictionary;
+
+export default appContent;
+```
+
+```typescript codeFormat={["typescript", "esm", "commonjs"]}
+import { getIntlayer } from "intlayer";
+
+const { title } = getIntlayer("app", "pl"); // "Cześć"
+```
+
+### Bez locale
+
+Pominięcie locale interpretuje zawartość przy użyciu `defaultLocale` zadeklarowanego w Twojej [konfiguracji](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/configuration.md).
+
+```typescript
+import { getIntlayer } from "intlayer";
+
+const { title } = getIntlayer("app"); // Interpretowane przy użyciu domyślnego locale
+```
+
+### Wewnątrz handlera serwera
+
+```typescript fileName="src/routes/greeting.ts" codeFormat="typescript"
+import { getIntlayer, getLocale } from "intlayer";
+
+export const greetingHandler = async (request: Request) => {
+  const locale = await getLocale({
+    getHeader: (name) => request.headers.get(name) ?? undefined,
+  });
+
+  const { title } = getIntlayer("app", locale);
+
+  return Response.json({ title });
+};
+```
+
+### Z selektorem (kolekcje i warianty)
+
+```typescript
+import { getIntlayer } from "intlayer";
+
+// Pojedynczy element kolekcji
+const secondPost = getIntlayer("blog-post", { item: 2, locale: "fr" });
+
+// Każdy element kolekcji jako uporządkowana tablica
+const allPosts = getIntlayer("blog-post", { locale: "fr" });
+
+// Nazwany wariant
+const banner = getIntlayer("banner", { variant: "black-friday", locale: "fr" });
+```
+
+---
+
+## Notatki dotyczące zachowania
+
+### Buforowanie
+
+Wyniki są zapamiętane w pamięci podręcznej na poziomie modułu, której kluczem jest `key + locale + selector`. Wielokrotne wywołanie `getIntlayer("app", "fr")` interpretuje słownik raz i zwraca ten sam obiekt.
+
+### Brakujące słowniki
+
+W trakcie rozwoju, żądanie klucza, który nie ma wygenerowanego słownika, loguje ostrzeżenie raz i zwraca bezpieczny proxy fallback: odczytanie `content.title` zwraca ciąg `"app.title"` zamiast rzucać błąd. To utrzymuje stronę użyteczną, podczas gdy brakująca deklaracja jest naprawiana. Uruchom kompilację Intlayer (lub serwer dev), aby słownik został wygenerowany.
+
+### Rozmiar pakietu
+
+`getIntlayer` reads the merged dictionary, which holds **every** locale. In client bundles, the [build plugins](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/bundle_optimization.md) rewrite the call so only the required content is shipped. When you read content outside of rendering (metadata, loaders, server functions) and want a single locale loaded on demand, use [`getIntlayerAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/intlayer/getIntlayerAsync.md) instead.
+
+---
+
+## Powiązane funkcje
+
+- [`getIntlayerAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/intlayer/getIntlayerAsync.md): Asynchroniczny odpowiednik ładujący pojedynczy chunk lokalizacji.
+- [`getDictionary`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/intlayer/getDictionary.md): Interpretuje obiekt słownika, który sam przekazujesz, zamiast szukać go po kluczu.
+- [`useIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/react-intlayer/useIntlayer.md): Równoważny hook React'a, odczytujący lokalizację od dostawcy.
+
+---
+
+## TypeScript
+
+```typescript
+function getIntlayer<
+  const T extends DictionaryKeys,
+  const A extends LocalesValues | DictionarySelector = DeclaredLocales,
+>(
+  key: T,
+  localeOrSelector?: A,
+  plugins?: Plugins[]
+): DeepTransformContent<
+  DictionaryRegistryResult<T, A>,
+  IInterpreterPluginState,
+  ExtractSelectorLocale<A>
+>;
+```

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

@@ -0,0 +1,141 @@
+---
+createdAt: 2026-08-23
+updatedAt: 2026-08-23
+title: Dokumentacja funkcji getIntlayerAsync | intlayer
+description: Dowiedz się, jak używać funkcji getIntlayerAsync z pakietu intlayer
+keywords:
+  - getIntlayerAsync
+  - dictionary
+  - dynamic import
+  - metadata
+  - bundle optimization
+  - Intlayer
+  - intlayer
+  - Internationalization
+  - Documentation
+  - JavaScript
+  - TypeScript
+slugs:
+  - doc
+  - packages
+  - intlayer
+  - getIntlayerAsync
+history:
+  - version: 9.4.0
+    date: 2026-08-23
+    changes: "Initial documentation"
+author: aymericzip
+---
+
+# Dokumentacja: Funkcja `getIntlayerAsync` w `intlayer`
+
+## Opis
+
+Funkcja `getIntlayerAsync` wybiera jeden słownik po jego kluczu i rozwiązuje jego zawartość dla danego locale'a, **ładując tylko ten locale**.
+
+Jest to asynchroniczny odpowiednik [`getIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/intlayer/getIntlayer.md), przeznaczony dla miejsc, gdzie słownik jest odczytywany poza renderowaniem — konstruktory `head` / metadanych tras, loadery, funkcje serwerowe.
+
+Podczas gdy `getIntlayer` ładuje scalony słownik zawierający każdy locale, [wtyczki budowania](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/bundle_optimization.md) (`@intlayer/babel`, `@intlayer/swc`) przepisują to wywołanie na `getDictionaryAsync(loaderMap, key, locale)`, wskazując na fragmenty poszczególnych locale'ów w `.intlayer/dynamic_dictionaries/`. Bundle w związku z tym zawiera tylko rzeczywiście żądany locale.
+
+Bez tych wtyczek — niezoptymalizowana kompilacja — wywołanie rozwiązuje się zamiast tego poprzez synchroniczny rejestr słownika: ta sama zawartość, bez podziału na locale'a.
+
+**Kluczowe funkcje:**
+
+- Takie same wpisane klucze, selektory i zwracana zawartość co `getIntlayer`
+- Ładuje tylko żądany fragment locale'a w zoptymalizowanych kompilacjach
+- Współbieżne wywołania dla tego samego fragmentu współdzielą jedno ładowanie
+- Bezpieczne do użycia w asynchronicznych konstruktorach metadanych, loaderach i funkcjach serwerowych
+
+---
+
+## Sygnatura Funkcji
+
+```typescript
+getIntlayerAsync(
+  key: DictionaryKeys,                        // Wymagane
+  localeOrSelector?: LocalesValues | DictionarySelector, // Opcjonalne
+  plugins?: Plugins[]                         // Opcjonalne
+): Promise<DeepTransformContent<...>>
+```
+
+---
+
+## Parametry
+
+- `key: DictionaryKeys`
+  - **Description**: Klucz słownika do odczytania, zadeklarowany w plikach zawartości.
+  - **Type**: `DictionaryKeys` — unija wszystkich zadeklarowanych kluczy słownika.
+  - **Required**: Yes
+
+- `localeOrSelector: LocalesValues | DictionarySelector`
+  - **Description**: Locale do interpretacji zawartości lub obiekt selektora dla [słowników dynamicznych](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/dynamic_dictionaries/index.md).
+    - `'fr'` — locale
+    - `{ item: 2 }` — element [kolekcji](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/dynamic_dictionaries/collections.md) (pomiń `item`, aby otrzymać wszystkie elementy jako tablicę)
+    - `{ variant: 'black-friday' }` — nazwana [wariant](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/dynamic_dictionaries/variants.md) (pomiń dla wariantu `default`)
+    - `{ variant: { id: 'prod_abc', userId: '123' } }` — wariant strukturyzowany
+    - Każdy selektor może zawierać locale: `{ item: 2, locale: 'fr' }`
+  - **Type**: `LocalesValues | DictionarySelector`
+  - **Required**: No (Optional) — domyślnie skonfigurowany `defaultLocale`.
+
+- `plugins: Plugins[]`
+  - **Description**: Niestandardowe transformatory węzłów zastępujące podstawowe pluginy interpretera. Zaawansowane użycie tylko.
+  - **Type**: `Plugins[]`
+  - **Required**: No (Optional)
+
+### Zwracane
+
+- **Typ**: `Promise<Content>` — promise rozwiązujący się do interpretowanej zawartości słownika, typizowanej z Twojej deklaracji.
+
+---
+
+## Przykład użycia
+
+### Podstawowe użycie
+
+```typescript codeFormat={["typescript", "esm", "commonjs"]}
+import { getIntlayerAsync } from "intlayer";
+
+const { title } = await getIntlayerAsync("app", "fr"); // "Bonjour"
+```
+
+---
+
+## `getIntlayer` vs `getIntlayerAsync`
+
+|                         | [`getIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/intlayer/getIntlayer.md) | `getIntlayerAsync`                                |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
+| Zwraca                  | Zawartość                                                                                                       | Obietnicę zawartości                              |
+| Słownik załadowany      | Połączony słownik (wszystkie języki)                                                                            | Chunk tylko żądanego języka                       |
+| Najlepiej nadaje się do | Renderowanie, synchroniczne ścieżki kodu                                                                        | Metadane, loadery, funkcje serwerowe              |
+| Wymaga pluginu?         | Nie                                                                                                             | Nie — podział na języki wymaga pluginów budowania |
+
+Obie funkcje akceptują te same argumenty i zwracają tę samą zawartość: przełączenie się między nimi zmienia tylko **kiedy** i **ile** jest ładowane.
+
+---
+
+## Powiązane funkcje
+
+- [`getIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/intlayer/getIntlayer.md): Synchroniczny odpowiednik odczytujący scalony słownik.
+- [`getDictionaryAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/intlayer/getDictionaryAsync.md): Funkcja niskiego poziomu, którą wtyczki kompilacji przepisują do tego wywołania.
+- [`getLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/intlayer/getLocale.md): Wykrywa locale przychodzącego żądania.
+
+---
+
+## TypeScript
+
+```typescript
+function getIntlayerAsync<
+  const T extends DictionaryKeys,
+  const A extends LocalesValues | DictionarySelector = DeclaredLocales,
+>(
+  key: T,
+  localeOrSelector?: A,
+  plugins?: Plugins[]
+): Promise<
+  DeepTransformContent<
+    DictionaryRegistryResult<T, A>,
+    IInterpreterPluginState,
+    ExtractSelectorLocale<A>
+  >
+>;
+```