@intlayer/docs 8.11.2 → 8.12.0-canary.0

package/docs/pl/intlayer_with_vanilla.md

@@ -1,8 +1,8 @@
 ---
 createdAt: 2026-03-31
-updatedAt: 2026-05-06
-title: Vanilla JS i18n - Jak przetłumaczyć aplikację Vanilla JS w 2026 roku
-description: Dowiedz się, jak uczynić swoją stronę Vanilla JS wielojęzyczną. Postępuj zgodnie z dokumentacją, aby ją umiędzynarodowić (i18n) i przetłumaczyć.
+updatedAt: 2026-05-31
+title: "Vanilla JS i18n - Kompletny przewodnik po tłumaczeniu swojej aplikacji"
+description: "Koniec z i18next. Przewodnik 2026 do budowania wielojęzycznej (i18n) aplikacji Vanilla JS. Tłumacz z agentami AI i optymalizuj rozmiar bundle, SEO i wydajność."
 keywords:
   - Międzynarodowienie
   - Dokumentacja
@@ -57,28 +57,45 @@ history:
 
 <TOC/>
 
-## Co to jest Intlayer?
+## Dlaczego Interlayer zamiast alternatyw?
 
-**Intlayer** to innowacyjna biblioteka międzynarodowienia (i18n) o otwartym kodzie źródłowym, zaprojektowana w celu uproszczenia obsługi wielojęzyczności w nowoczesnych aplikacjach internetowych.
+W porównaniu do głównych rozwiązań, takich jak `i18next` czy `i18n.js`, Intlayer jest rozwiązaniem wyposażonym w zintegrowane optymalizacje, takie jak:
 
-Dzięki Intlayer możesz:
+**Pełne pokrycie Vanilla JS**
 
-- **Łatwo zarządzać tłumaczeniami** używając deklaratywnych słowników na poziomie komponentów.
-- **Dynamicznie lokalizować metadane**, trasy i treści.
-- **Zapewnić wsparcie dla TypeScript** dzięki automatycznie generowanym typom, co poprawia autouzupełnianie i wykrywanie błędów.
-- **Korzystać z zaawansowanych funkcji**, takich jak dynamiczne wykrywanie i przełączanie języka.
+Intlayer jest zoptymalizowany do doskonałej współpracy z Vanilla JavaScript, oferując **zarządzanie treścią niezależnie od platformy**, **obsługę TypeScript** i wszystkie funkcje potrzebne do skalowania internacjonalizacji (i18n).
 
-Ten poradnik pokazuje, jak używać Intlayer w aplikacji Vanilla JavaScript **bez użycia menedżera pakietów lub bundlera** (takiego jak Vite, Webpack itp.).
+**Rozmiar bundle'a**
 
-Jeśli Twoja aplikacja używa bundlera (np. Vite), zalecamy zamiast tego skorzystanie z [Poradnika Vite + Vanilla JS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/intlayer_with_vite+vanilla.md).
+Zamiast ładować ogromne pliki JSON na swoje strony, ładuj tylko niezbędną treść. Intlayer pomaga **zmniejszyć rozmiary bundle'a i stron nawet o 50%**.
 
-Używając samodzielnego pakietu (standalone bundle), możesz zaimportować Intlayer bezpośrednio do plików HTML za pomocą jednego pliku JavaScript, co czyni go idealnym dla starszych projektów lub prostych stron statycznych.
+**Łatwość konserwacji**
+
+Określanie zakresu zawartości aplikacji **ułatwia konserwację** aplikacji na dużą skalę. Możesz powielić lub usunąć pojedynczy folder funkcji bez obciążania psychicznego koniecznością przeglądania całej bazy kodu zawartości. Dodatkowo Inlayer jest **w pełni napisany**, aby zapewnić dokładność treści.
+
+**Agent AI**
+
+Wspólna lokalizacja treści **zmniejsza potrzebny kontekst** dzięki modelom dużego języka (LLM). Intlayer zawiera także zestaw narzędzi, taki jak **CLI** do sprawdzania brakujących tłumaczeń**[LSP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/lsp.md)**, **[MCP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/mcp_server.md)** i **[umiejętności agenta](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/agent_skills.md)**, aby praca programisty (DX) była jeszcze płynniejsza dla agentów AI.
+
+**Automatyzacja**
+
+Korzystaj z automatyzacji, aby tłumaczyć w swoim potoku CI/CD przy użyciu wybranego LLM na koszt dostawcy sztucznej inteligencji. Intlayer oferuje także **kompilator** do automatyzacji ekstrakcji treści, a także [platformę internetową] (https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md), która pomaga **tłumaczyć w tle**.
+
+**Wydajność**
+
+Łączenie ogromnych plików JSON z komponentami może prowadzić do problemów z wydajnością i reaktywnością. Inlayer optymalizuje ładowanie treści w czasie kompilacji.
+
+**Skalowanie bez użycia dewelopera**
+
+Więcej niż tylko rozwiązanie i18n, Intlayer zapewnia **samodzielny [edytor wizualny](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_visual_editor.md)** i **[pełny CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md)**, który pomoże Ci zarządzać wielojęzyczną treścią w **w czasie rzeczywistym**, dzięki czemu współpraca z tłumaczami, copywriterami i innymi członkami zespołu będzie płynna. Treść może być przechowywana lokalnie i/lub zdalnie.
 
 ---
 
 ## Przewodnik krok po kroku konfiguracji Intlayer w aplikacji Vanilla JS
 
-### Krok 1: Instalacja zależności
+<Steps>
+
+<Step number={1} title="Instalacja zależności">
 
 Zainstaluj niezbędne pakiety za pomocą npm:
 
@@ -138,7 +155,9 @@ bun x intlayer build
 
 > Eksport bundlingu z CLI `intlayer standalone` generuje zoptymalizowaną kompilację dzięki usuwaniu nieużywanych kodów (tree-shaking) nieużywanych pakietów, lokalizacji i nieistotnej logiki (takiej jak przekierowania lub prefiksy), specyficznych dla Twojej konfiguracji.
 
-### Krok 2: Konfiguracja Twojego projektu
+</Step>
+
+<Step number={2} title="Konfiguracja Twojego projektu">
 
 Utwórz plik konfiguracyjny, aby skonfigurować języki Twojej aplikacji:
 
@@ -162,7 +181,9 @@ export default config;
 
 > Za pomocą tego pliku konfiguracyjnego możesz ustawić zlokalizowane adresy URL, przekierowania middleware, nazwy ciasteczek, lokalizację i rozszerzenie deklaracji treści, wyłączyć logi Intlayer w konsoli i wiele więcej. Pełną listę dostępnych parametrów znajdziesz w [dokumentacji konfiguracji](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/configuration.md).
 
-### Krok 3: Zaimportuj pakiet do HTML
+</Step>
+
+<Step number={3} title="Zaimportuj pakiet do HTML">
 
 Po wygenerowaniu pakietu `intlayer.js`, możesz go zaimportować do swojego pliku HTML:
 
@@ -186,7 +207,9 @@ Po wygenerowaniu pakietu `intlayer.js`, możesz go zaimportować do swojego plik
 
 Pakiet udostępnia `Intlayer` i `VanillaIntlayer` jako obiekty globalne na `window`.
 
-### Krok 4: Uruchom Intlayer w punkcie wejścia (entry point)
+</Step>
+
+<Step number={4} title="Uruchom Intlayer w punkcie wejścia">
 
 W swoim `src/main.js` wywołaj `installIntlayer()` **zanim** jakakolwiek treść zostanie wyrenderowana, aby globalny singleton języka był gotowy.
 
@@ -206,7 +229,9 @@ installIntlayer();
 installIntlayerMarkdown();
 ```
 
-### Krok 5: Zadeklaruj swoje treści
+</Step>
+
+<Step number={5} title="Zadeklaruj swoje treści">
 
 Twórz i zarządzaj swoimi deklaracjami treści, aby przechowywać tłumaczenia:
 
@@ -284,7 +309,9 @@ export default appContent;
 >
 > Więcej szczegółów znajdziesz w [dokumentacji deklaracji treści](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/dictionary/content_file.md).
 
-### Krok 6: Użyj Intlayer w swoim JavaScript
+</Step>
+
+<Step number={6} title="Użyj Intlayer w swoim JavaScript">
 
 Obiekt `window.VanillaIntlayer` dostarcza pomocników API: `useIntlayer(key, locale?)` zwraca przetłumaczoną treść dla danego klucza.
 
@@ -318,7 +345,9 @@ document.querySelector(".read-the-docs").textContent = String(
 > img.alt = content.viteLogoLabel.value;
 > ```
 
-### (Opcjonalnie) Krok 7: Zmień język swojej treści
+</Step>
+
+<Step number={7} title="Zmień język swojej treści" isOptional={true}>
 
 Aby zmienić język treści, użyj funkcji `setLocale` udostępnianej przez `useLocale`.
 
@@ -353,7 +382,9 @@ export function setupLocaleSwitcher(container) {
 }
 ```
 
-### (Opcjonalnie) Krok 8: Przełącz atrybuty języka i kierunku HTML
+</Step>
+
+<Step number={8} title="Przełącz atrybuty języka i kierunku HTML" isOptional={true}>
 
 Zaktualizuj atrybuty `lang` i `dir` tagu `<html>`, aby pasowały do bieżącego języka dla dostępności i SEO.
 
@@ -371,7 +402,9 @@ useLocale({
 });
 ```
 
-### (Opcjonalnie) Krok 9: Leniwe ładowanie słowników na język (lazy load)
+</Step>
+
+<Step number={9} title="Leniwe ładowanie słowników na język" isOptional={true}>
 
 Jeśli chcesz leniwie ładować słowniki dla każdego języka, możesz użyć `useDictionaryDynamic`. Jest to przydatne, jeśli nie chcesz pakować wszystkich tłumaczeń w początkowym pliku `intlayer.js`.
 
@@ -393,6 +426,9 @@ const unsubscribe = useDictionaryDynamic(
 ```
 
 > Uwaga: `useDictionaryDynamic` wymaga, aby słowniki były dostępne jako oddzielne pliki ESM. Podejście to jest zazwyczaj stosowane, jeśli masz serwer WWW serwujący słowniki.
+> </Step>
+
+</Steps>
 
 ### Konfiguracja TypeScript
 

package/docs/pl/intlayer_with_vite+lit.md

@@ -1,8 +1,8 @@
 ---
 createdAt: 2026-03-23
-updatedAt: 2026-05-06
-title: Vite + Lit i18n - Jak przetłumaczyć aplikację Lit w 2026 roku
-description: Dowiedz się, jak sprawić, by Twoja strona Vite i Lit była wielojęzyczna. Postępuj zgodnie z dokumentacją dotyczącą internacjonalizacji (i18n) i tłumaczenia.
+updatedAt: 2026-05-31
+title: "Vite + Lit i18n - Kompletny przewodnik po tłumaczeniu swojej aplikacji"
+description: "Koniec z i18next. Przewodnik 2026 do budowania wielojęzycznej (i18n) aplikacji Vite + Lit. Tłumacz z agentami AI i optymalizuj rozmiar bundle, SEO i wydajność."
 keywords:
   - Internacjonalizacja
   - Dokumentacja
@@ -57,22 +57,45 @@ history:
 
 <TOC/>
 
-## Czym jest Intlayer?
+## Dlaczego Interlayer zamiast alternatyw?
 
-**Intlayer** to innowacyjna biblioteka internacjonalizacji (i18n) typu open-source, zaprojektowana w celu uproszczenia obsługi wielojęzyczności w nowoczesnych aplikacjach internetowych.
+W porównaniu do głównych rozwiązań, takich jak „lit-localize” czy „i18next”, Intlayer jest rozwiązaniem wyposażonym w zintegrowane optymalizacje, takie jak:
 
-Dzięki Intlayer możesz:
+**Pełne pokrycie światłem**
 
-- **Łatwo zarządzać tłumaczeniami** za pomocą deklaratywnych słowników na poziomie komponentów.
-- **Dynamicznie lokalizować metadane**, trasy i treści.
-- **Zapewnić obsługę TypeScript** dzięki automatycznie generowanym typom, poprawiając autouzupełnianie i wykrywanie błędów.
-- **Korzystać z zaawansowanych funkcji**, takich jak dynamiczne wykrywanie i przełączanie języka.
+Intlayer jest zoptymalizowany do doskonałej współpracy z Lit, oferując **zakres treści na poziomie komponentów sieciowych**, **obsługę TypeScript** i wszystkie funkcje potrzebne do skalowania umiędzynarodowienia (i18n).
+
+**Rozmiar bundle'a**
+
+Zamiast ładować ogromne pliki JSON na swoje strony, ładuj tylko niezbędną treść. Intlayer pomaga **zmniejszyć rozmiary bundle'a i stron nawet o 50%**.
+
+**Łatwość konserwacji**
+
+Określanie zakresu zawartości aplikacji **ułatwia konserwację** aplikacji na dużą skalę. Możesz powielić lub usunąć pojedynczy folder funkcji bez obciążania psychicznego koniecznością przeglądania całej bazy kodu zawartości. Dodatkowo Inlayer jest **w pełni napisany**, aby zapewnić dokładność treści.
+
+**Agent AI**
+
+Wspólna lokalizacja treści **zmniejsza potrzebny kontekst** dzięki modelom dużego języka (LLM). Intlayer zawiera także zestaw narzędzi, taki jak **CLI** do sprawdzania brakujących tłumaczeń**[LSP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/lsp.md)**, **[MCP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/mcp_server.md)** i **[umiejętności agenta](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/agent_skills.md)**, aby praca programisty (DX) była jeszcze płynniejsza dla agentów AI.
+
+**Automatyzacja**
+
+Korzystaj z automatyzacji, aby tłumaczyć w swoim potoku CI/CD przy użyciu wybranego LLM na koszt dostawcy sztucznej inteligencji. Intlayer oferuje także **kompilator** do automatyzacji ekstrakcji treści, a także [platformę internetową] (https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md), która pomaga **tłumaczyć w tle**.
+
+**Wydajność**
+
+Łączenie ogromnych plików JSON z komponentami może prowadzić do problemów z wydajnością i reaktywnością. Inlayer optymalizuje ładowanie treści w czasie kompilacji.
+
+**Skalowanie bez użycia dewelopera**
+
+Więcej niż tylko rozwiązanie i18n, Intlayer zapewnia **samodzielny [edytor wizualny](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_visual_editor.md)** i **[pełny CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md)**, który pomoże Ci zarządzać wielojęzyczną treścią w **w czasie rzeczywistym**, dzięki czemu współpraca z tłumaczami, copywriterami i innymi członkami zespołu będzie płynna. Treść może być przechowywana lokalnie i/lub zdalnie.
 
 ---
 
 ## Przewodnik krok po kroku dotyczący konfiguracji Intlayer w aplikacji Vite i Lit
 
-### Krok 1: Instalacja zależności
+<Steps>
+
+<Step number={1} title="Instalacja zależności">
 
 Zainstaluj niezbędne pakiety za pomocą npm:
 
@@ -110,7 +133,9 @@ bun x intlayer init
 - **vite-intlayer**
   Zawiera wtyczkę Vite do integracji Intlayer z [bundlerem Vite](https://vite.dev/guide/why.html#why-bundle-for-production), a także middleware do wykrywania preferowanego języka użytkownika, zarządzania plikami cookie i obsługi przekierowań adresów URL.
 
-### Krok 2: Konfiguracja Twojego projektu
+</Step>
+
+<Step number={2} title="Konfiguracja Twojego projektu">
 
 Utwórz plik konfiguracyjny, aby skonfigurować języki Twojej aplikacji:
 
@@ -134,7 +159,9 @@ export default config;
 
 > Za pomocą tego pliku konfiguracyjnego możesz ustawić zlokalizowane adresy URL, przekierowania middleware, nazwy plików cookie, lokalizację i rozszerzenie deklaracji treści, wyłączyć logi Intlayer w konsoli i wiele więcej. Pełną listę dostępnych parametrów znajdziesz w [dokumentacji konfiguracji](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/configuration.md).
 
-### Krok 3: Zintegruj Intlayer z konfiguracją Vite
+</Step>
+
+<Step number={3} title="Zintegruj Intlayer z konfiguracją Vite">
 
 Dodaj wtyczkę intlayer do swojej konfiguracji.
 
@@ -150,7 +177,9 @@ export default defineConfig({
 
 > Wtyczka Vite `intlayer()` służy do integracji Intlayer z Vite. Zapewnia budowanie plików deklaracji treści i monitoruje je w trybie deweloperskim. Definiuje zmienne środowiskowe Intlayer wewnątrz aplikacji Vite. Dodatkowo zapewnia aliasy w celu optymalizacji wydajności.
 
-### Krok 4: Uruchomienie Intlayer w punkcie wejścia
+</Step>
+
+<Step number={4} title="Uruchomienie Intlayer w punkcie wejścia">
 
 Wywołaj `installIntlayer()` **przed** zarejestrowaniem jakichkolwiek niestandardowych elementów, aby globalny singleton języka był gotowy, gdy pierwszy element się połączy.
 
@@ -175,7 +204,9 @@ installIntlayerMarkdown();
 import "./my-element.js";
 ```
 
-### Krok 5: Zadeklaruj swoją treść
+</Step>
+
+<Step number={5} title="Zadeklaruj swoją treść">
 
 Twórz i zarządzaj deklaracjami treści w celu przechowywania tłumaczeń:
 
@@ -261,7 +292,9 @@ export default appContent;
 >
 > Więcej szczegółów znajdziesz w [dokumentacji deklaracji treści](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/dictionary/content_file.md).
 
-### Krok 6: Wykorzystaj Intlayer w swoim LitElement
+</Step>
+
+<Step number={6} title="Wykorzystaj Intlayer w swoim LitElement">
 
 Użyj `useIntlayer` wewnątrz `LitElement`. Zwraca proxy `ReactiveController`, który automatycznie wyzwala ponowne renderowanie przy każdej zmianie aktywnego języka - nie jest wymagana żadna dodatkowa konfiguracja.
 
@@ -306,7 +339,9 @@ export class MyElement extends LitElement {
 > html`<img alt=${String(content.viteLogo)} />`;
 > ```
 
-### (Opcjonalnie) Krok 7: Zmiana języka treści
+</Step>
+
+<Step number={7} title="Zmiana języka treści" isOptional={true}>
 
 Aby zmienić język treści, użyj metody `setLocale` udostępnionej przez kontroler `useLocale`.
 
@@ -341,7 +376,9 @@ export class LocaleSwitcher extends LitElement {
 }
 ```
 
-### (Opcjonalnie) Krok 8: Renderowanie treści Markdown i HTML
+</Step>
+
+<Step number={8} title="Renderowanie treści Markdown i HTML" isOptional={true}>
 
 Intlayer obsługuje deklaracje treści `md()` i `html()`. W Lit skompilowane wyjście jest wstrzykiwane jako surowy kod HTML za pomocą dyrektywy `unsafeHTML`.
 
@@ -391,7 +428,9 @@ export class MyElement extends LitElement {
 > [!TIP]
 > `String(content.editNote)` wywołuje `toString()` na `IntlayerNode`, co zwraca surowy ciąg znaków Markdown. Przekaż go do `compileMarkdown`, aby uzyskać ciąg znaków HTML, a następnie wyrenderuj go za pomocą dyrektywy `unsafeHTML` z biblioteki Lit.
 
-### (Opcjonalnie) Krok 9: Dodaj zlokalizowany routing do swojej aplikacji
+</Step>
+
+<Step number={9} title="Dodaj zlokalizowany routing do swojej aplikacji" isOptional={true}>
 
 Aby stworzyć unikalne trasy dla każdego języka (przydatne dla SEO), możesz użyć routera po stronie klienta wraz z pomocnikami Intlayer `localeMap` / `localeFlatMap` oraz wtyczką Vite `intlayerProxy` do wykrywania języka po stronie serwera.
 
@@ -408,7 +447,9 @@ export default defineConfig({
 });
 ```
 
-### (Opcjonalnie) Krok 10: Zmiana adresu URL po zmianie języka
+</Step>
+
+<Step number={10} title="Zmiana adresu URL po zmianie języka" isOptional={true}>
 
 Aby zaktualizować adres URL w przeglądarce po zmianie języka, użyj `useRewriteURL` wraz z przełącznikiem języka:
 
@@ -446,7 +487,9 @@ export class LocaleSwitcher extends LitElement {
 }
 ```
 
-### (Opcjonalnie) Krok 11: Przełączanie atrybutów języka i kierunku HTML
+</Step>
+
+<Step number={11} title="Przełączanie atrybutów języka i kierunku HTML" isOptional={true}>
 
 Zaktualizuj atrybuty `lang` i `dir` tagu `<html>`, aby odpowiadały bieżącemu językowi w celu zapewnienia dostępności i SEO.
 
@@ -471,7 +514,9 @@ export class MyElement extends LitElement {
 }
 ```
 
-### (Opcjonalnie) Krok 12: Wyodrębnij treść swoich komponentów
+</Step>
+
+<Step number={12} title="Wyodrębnij treść swoich komponentów" isOptional={true}>
 
 Jeśli masz istniejącą bazę kodu, transformacja tysięcy plików może być czasochłonna.
 
@@ -511,6 +556,10 @@ const config: IntlayerConfig = {
 export default config;
 ```
 
+</Step>
+
+</Steps>
+
 ### (Opcjonalnie) Sitemap i robots.txt (generacja przy buildzie)
 
 Intlayer udostępnia `generateSitemap` i `getMultilingualUrls` - narzędzia do formatowania wielojęzycznych plików `sitemap.xml` i `robots.txt` dla crawlerów i automatycznego zapisu do `public/`. Zwykle uruchamia się mały skrypt Node **przed** Vite (np. hooki npm `predev` / `prebuild`).