@intlayer/docs 7.0.0-canary.2 → 7.0.0-canary.3

package/docs/pl/releases/v7.md

@@ -0,0 +1,486 @@
+---
+createdAt: 2025-09-22
+updatedAt: 2025-09-23
+title: Nowy Intlayer v7 - Co nowego?
+description: Odkryj, co nowego w Intlayer v7. Znaczące ulepszenia wydajności, doświadczenia deweloperskiego oraz nowe funkcje usprawniające proces internacjonalizacji.
+keywords:
+  - Intlayer
+  - Lokalizacja
+  - Rozwój
+  - Wydajność
+  - Doświadczenie Dewelopera
+  - Funkcje
+  - React
+  - Next.js
+  - JavaScript
+  - TypeScript
+slugs:
+  - doc
+  - releases
+  - v7
+---
+
+# Nowy Intlayer v7 - Co nowego?
+
+Witamy w Intlayer v7! To duże wydanie wprowadza znaczące ulepszenia w wydajności, bezpieczeństwie typów oraz doświadczeniu deweloperskim. Poniżej znajdują się najważniejsze zmiany, wraz z notatkami migracyjnymi i praktycznymi przykładami.
+
+## Najważniejsze zmiany
+
+- Strategia buforowania dla szybszych kompilacji
+- Ulepszone generowanie typów TypeScript z typami specyficznymi dla lokalizacji
+- Optymalizacja pakietu: lokalizacje jako łańcuchy znaków zamiast enumów
+- Nowe tryby routingu: `prefix-no-default`, `prefix-all`, `no-prefix`, `search-params`
+- Przechowywanie lokalizacji zgodne z RODO, domyślnie w localStorage
+- Elastyczna konfiguracja przechowywania: cookies, localStorage, sessionStorage lub wiele jednocześnie
+- Pakiet Visual Editor mniejszy o 30%
+- Rozszerzone opcje konfiguracji middleware
+- Zaktualizowane zachowanie polecenia fill dla lepszego zarządzania treścią
+- Zwiększona stabilność dzięki pełnym aktualizacjom plików deklaracji treści
+- Inteligentne zarządzanie ponownymi próbami dla dokładności tłumaczeń
+- Równoległe przetwarzanie dla szybszej obsługi tłumaczeń
+- Inteligentne dzielenie na fragmenty, aby obsłużyć duże pliki w ramach limitów kontekstu AI
+
+---
+
+## Wydajność: Caching dla szybszych kompilacji
+
+Zamiast przebudowywać deklaracje treści za pomocą esbuild przy każdym buildzie, wersja 7 wprowadza strategię cache’owania, która przyspiesza proces budowania.
+
+```bash
+npx intlayer build
+```
+
+Nowy system cache’owania:
+
+- Przechowuje skompilowane deklaracje treści, aby uniknąć zbędnego przetwarzania
+- Wykrywa zmiany i przebudowuje tylko zmodyfikowane pliki
+- Znacząco skraca czas budowania dużych projektów
+
+---
+
+## TypeScript: Generowanie typów specyficznych dla lokalizacji
+
+Typy TypeScript są teraz generowane dla każdej lokalizacji osobno, co zapewnia silniejsze typowanie i eliminuje typy unii obejmujące wszystkie lokalizacje.
+
+**Zachowanie w wersji 6:**
+
+```tsx
+const content = getIntlayer("my-title-content", "en");
+// typeof content = { title: "My title" } | { title: "Mon titre" } | { title: "Mi título" }
+```
+
+**Zachowanie w wersji 7:**
+
+```tsx
+const content = getIntlayer("my-title-content", "en");
+// typeof content = { title: "My title" }
+```
+
+Korzyści:
+
+- Bardziej precyzyjne podpowiedzi w Twoim IDE
+- Lepsze bezpieczeństwo typów bez zanieczyszczenia typów między lokalizacjami
+- Poprawiona wydajność dzięki zmniejszeniu złożoności typów
+
+---
+
+## Optymalizacja bundla: Lokalizacje jako stringi
+
+Typ `Locales` nie jest już enumeracją, co oznacza, że jest teraz w pełni możliwy do tree-shakingu i nie będzie powiększał Twojego bundla o tysiące nieużywanych rekordów lokalizacji.
+
+**v6:**
+
+```typescript
+import { Locales } from "intlayer";
+// Enum zawierający wszystkie lokalizacje -> nie jest możliwy do tree-shakingu
+
+const locale: Locales = Locales.ENGLISH;
+```
+
+**v7:**
+
+```typescript
+import { Locales, Locale } from "intlayer";
+// Typ string -> w pełni możliwy do tree-shakingu
+
+const locale: Locale = Locales.ENGLISH;
+```
+
+> Ponieważ `Locales` nie jest już enumeracją, będziesz musiał zmienić typ z `Locales` na `Locale`, aby uzyskać lokalizację jako typ.
+
+Zobacz [szczegóły implementacji](https://github.com/aymericzip/intlayer/blob/main/packages/%40intlayer/types/src/index.ts) po więcej informacji.
+
+---
+
+## Nowe tryby routingu dla większej elastyczności
+
+Wersja v7 wprowadza zunifikowaną konfigurację `routing.mode`, która zastępuje poprzednie opcje `prefixDefault` i `noPrefix`, oferując bardziej szczegółową kontrolę nad strukturą URL.
+
+### Dostępne tryby routingu
+
+- **`prefix-no-default`** (domyślny): Domyślna lokalizacja nie ma prefiksu, inne lokalizacje mają
+  - `/dashboard` (en) lub `/fr/dashboard` (fr)
+- **`prefix-all`**: Wszystkie lokalizacje mają prefiks
+  - `/en/dashboard` (en) lub `/fr/dashboard` (fr)
+- **`no-prefix`**: Brak prefiksów lokalizacji w URL (lokalizacja obsługiwana przez storage/headers)
+  - `/dashboard` dla wszystkich lokalizacji
+- **`search-params`**: Lokalizacja przekazywana jako parametr zapytania
+  - `/dashboard?locale=en` lub `/dashboard?locale=fr`
+
+### Podstawowa konfiguracja
+
+```typescript
+// intlayer.config.ts
+export default {
+  internationalization: {
+    locales: ["en", "fr", "es"],
+    defaultLocale: "en",
+  },
+  routing: {
+    mode: "prefix-no-default", // domyślnie
+  },
+};
+```
+
+---
+
+## Zgodność z RODO: storage w localStorage / cookies
+
+Wersja v7 stawia na prywatność użytkownika, używając `localStorage` jako domyślnego mechanizmu przechowywania zamiast cookies. Ta zmiana pomaga w zgodności z RODO, unikając wymagań dotyczących zgody na cookies dla preferencji lokalizacji.
+
+### Opcje konfiguracji storage
+
+Nowe pole `routing.storage` jest również dostępne oprócz wcześniejszych opcji `middleware.cookieName` i `middleware.serverSetCookie`, oferując elastyczne konfiguracje przechowywania:
+
+```typescript
+// Wyłącz przechowywanie
+storage: false
+
+// Proste typy przechowywania
+storage: 'cookie'
+storage: 'localStorage'
+storage: 'sessionStorage'
+
+// Cookie z niestandardowymi atrybutami
+storage: {
+  type: 'cookie',
+  name: 'custom-locale',
+  domain: '.example.com',
+  secure: true,
+  sameSite: 'strict'
+}
+
+// localStorage z niestandardowym kluczem
+storage: {
+  type: 'localStorage',
+  name: 'custom-locale'
+}
+
+// Wiele typów przechowywania dla redundancji
+storage: ['cookie', 'localStorage']
+```
+
+### Przykład konfiguracji zgodnej z RODO
+
+Dla aplikacji produkcyjnych, które muszą wyważyć funkcjonalność z zgodnością z RODO:
+
+```typescript
+// intlayer.config.ts
+export default {
+  internationalization: {
+    locales: ["en", "fr", "es"],
+    defaultLocale: "en",
+  },
+  routing: {
+    mode: "prefix-no-default",
+    storage: [
+      {
+        type: "localStorage", // Główne przechowywanie (nie wymaga zgody)
+        name: "user-locale",
+      },
+      {
+        type: "cookie", // Opcjonalne przechowywanie w ciasteczkach (wymaga zgody)
+        name: "user-locale",
+        secure: true,
+        sameSite: "strict",
+        httpOnly: false,
+      },
+    ],
+  },
+};
+```
+
+### Włączanie / wyłączanie przechowywania w ciasteczkach
+
+Przykład użycia w React / Next.js:
+
+Można zdefiniować globalnie:
+
+```typescript
+<IntlayerProvider isCookieEnabled={false}>
+  <App />
+</IntlayerProvider>
+```
+
+Można nadpisać lokalnie dla każdego hooka:
+
+```ts
+const { setLocale } = useLocale({ isCookieEnabled: false });
+
+setLocale("en");
+```
+
+**Uwaga:** Cookies są domyślnie włączone.
+**Uwaga:** Sprawdź [wymagania dotyczące plików cookie zgodne z RODO](https://gdpr.eu/cookies/) dla swojego konkretnego przypadku użycia.
+
+---
+
+## Edytor wizualny: pakiet o 30% mniejszy
+
+Pakiet Edytora wizualnego został zoptymalizowany i jest o 30% mniejszy niż poprzednia wersja, dzięki:
+
+- Poprawie wydajności edytora kodu
+- Usunięciu niepotrzebnych zależności od pakietów rdzenia Intlayer
+- Lepszemu tree-shakingowi i bundlowaniu modułów
+
+Skutkuje to szybszym czasem pobierania i lepszą wydajnością działania Twojej aplikacji.
+
+---
+
+## Komenda fill: Zaktualizowane zachowanie dla lepszego zarządzania treścią
+
+Wersja 7 wprowadza ulepszone zachowanie komendy `fill`, zapewniając bardziej przewidywalne i elastyczne zarządzanie treścią:
+
+### Nowe zachowanie polecenia fill
+
+- **`fill: true`** - Nadpisuje bieżący plik wypełnioną zawartością dla wszystkich lokalizacji
+- **`fill: "ścieżka/do/pliku"`** - Wypełnia określony plik bez modyfikowania bieżącego pliku
+- **`fill: false`** - Całkowicie wyłącza automatyczne wypełnianie
+
+### Ulepszone wsparcie dla złożonych struktur zawartości
+
+Polecenie fill obsługuje teraz złożone struktury deklaracji zawartości, w tym:
+
+- **Obiekty złożone**: Deklaracje zawartości, które odwołują się do innych obiektów
+- **Zawartość destrukturyzowana**: Zawartość wykorzystująca wzorce destrukturyzacji
+- **Zagnieżdżone odwołania**: Obiekty wywołujące się nawzajem w złożonych hierarchiach
+- **Dynamiczne struktury zawartości**: Zawartość z warunkowymi lub obliczanymi właściwościami
+
+### Korzyści
+
+- **Jasniejszy zamiar**: Zachowanie jest teraz bardziej jednoznaczne co do tego, co jest modyfikowane
+- **Lepsze rozdzielenie**: Pliki z zawartością mogą być przechowywane oddzielnie od wypełnionych tłumaczeń
+- **Ulepszony przepływ pracy**: Deweloperzy mają większą kontrolę nad miejscem przechowywania tłumaczeń
+- **Wsparcie dla złożonych struktur**: Obsługa zaawansowanych architektur zawartości z wieloma powiązanymi obiektami
+
+### Przykład użycia
+
+```typescript
+// Nadpisz bieżący plik wszystkimi lokalizacjami
+const content = {
+  key: "example",
+  fill: true, // Nadpisuje ten plik
+  content: {
+    title: "Hello World",
+  },
+};
+
+// Wypełnij osobny plik bez modyfikacji bieżącego pliku
+const content = {
+  key: "example",
+  fill: "./translations.json", // Tworzy/aktualizuje translations.json
+  content: {
+    title: "Hello World",
+  },
+};
+
+// Wyłącz automatyczne wypełnianie
+const content = {
+  key: "example",
+  fill: false, // Brak automatycznego wypełniania
+  content: {
+    title: "Hello World",
+  },
+};
+
+// Złożona struktura treści z obiektami złożonymi
+const sharedContent = {
+  buttons: {
+    save: "Zapisz",
+    cancel: "Anuluj",
+  },
+};
+
+const content = {
+  key: "complex-example",
+  fill: true,
+  content: {
+    // Odwołania do innych obiektów
+    sharedContent,
+
+    // Rozpakowana zawartość
+    ...sharedContent,
+
+    // Zagnieżdżone odwołania
+    sections: [
+      {
+        ...sharedContent.buttons,
+        header: "Sekcja 1",
+      },
+    ],
+  },
+};
+```
+
+---
+
+## Zwiększona stabilność i zarządzanie tłumaczeniami
+
+Wersja 7 wprowadza kilka usprawnień, które czynią tłumaczenie treści bardziej niezawodnym i efektywnym:
+
+### Pełne aktualizacje plików deklaracji treści
+
+System teraz aktualizuje pliki `.content.{ts,js,cjs,mjs}` zamiast częściowych aktualizacji, co zapewnia:
+
+- **Integralność danych**: Pełne przepisywanie plików zapobiega częściowym aktualizacjom, które mogłyby uszkodzić zawartość
+- **Spójność**: Wszystkie lokalizacje są aktualizowane atomowo, co utrzymuje synchronizację
+- **Niezawodność**: Zmniejsza ryzyko niekompletnych lub uszkodzonych plików zawartości
+
+### Inteligentne zarządzanie ponownymi próbami
+
+Nowe mechanizmy ponownych prób zapobiegają przesyłaniu zawartości w niepoprawnych formatach i unikają przerwania całego procesu wypełniania, jeśli jedno żądanie się nie powiedzie.
+
+### Równoległość dla szybszego przetwarzania
+
+Operacje tłumaczenia są teraz wykonywane w kolejce, aby uruchamiać je równolegle. Znacząco przyspiesza to proces.
+
+### Inteligentne dzielenie na fragmenty dla dużych plików
+
+Zaawansowane strategie dzielenia na fragmenty radzą sobie z dużymi plikami zawartości, nie przekraczając limitów kontekstu AI:
+
+### Przykładowy przebieg pracy
+
+```typescript
+// Duży plik zawartości jest automatycznie dzielony na fragmenty
+const content = {
+  key: "large-documentation",
+  fill: true,
+  content: {
+    // Duża zawartość automatycznie dzielona na fragmenty do przetwarzania przez AI
+    introduction: "..." // ponad 5000 znaków
+    sections: [
+      // Wiele dużych sekcji
+    ]
+  }
+};
+```
+
+System automatycznie:
+
+1. Analizuje rozmiar i strukturę zawartości
+2. Odpowiednio dzieli zawartość na fragmenty
+3. Przetwarza fragmenty równolegle
+4. Waliduje i ponawia próby w razie potrzeby
+5. Odtwarza kompletny plik
+
+---
+
+## Notatki migracyjne z wersji v6
+
+### Usunięte konfiguracje
+
+- **`middleware.cookieName`**: Zastąpione przez `routing.storage`
+- **`middleware.serverSetCookie`**: Zastąpione przez `routing.storage`
+- **`middleware.prefixDefault`**: Zastąpione przez `routing.mode`
+- **`middleware.noPrefix`**: Zastąpione przez `routing.mode`
+
+### Mapowanie migracji
+
+#### Mapowanie konfiguracji
+
+| Konfiguracja v6            | Konfiguracja v7                                     |
+| -------------------------- | --------------------------------------------------- |
+| `autoFill: xxx`            | `fill: xxx`                                         |
+| `prefixDefault: false`     | `mode: 'prefix-no-default'`                         |
+| `prefixDefault: true`      | `mode: 'prefix-all'`                                |
+| `noPrefix: true`           | `mode: 'no-prefix'`                                 |
+| `cookieName: 'my-locale'`  | `storage: { type: 'cookie', name: 'my-locale' }`    |
+| `serverSetCookie: 'never'` | `storage: false` lub usuń cookie z tablicy storage` |
+
+#### Przykład migracji
+
+**Przed (v6):**
+
+```typescript
+export default {
+  middleware: {
+    headerName: "x-intlayer-locale",
+    cookieName: "intlayer-locale",
+    prefixDefault: false,
+    basePath: "",
+    serverSetCookie: "always",
+    noPrefix: false,
+  },
+};
+```
+
+**Po (v7):**
+
+```typescript
+export default {
+  routing: {
+    mode: "prefix-no-default",
+    storage: "localStorage", // lub 'cookie', jeśli potrzebujesz przechowywania w ciasteczkach
+    headerName: "x-intlayer-locale",
+    basePath: "",
+    detectLocaleOnPrefetchNoPrefix: false,
+  },
+};
+```
+
+#### Mapowanie zawartości słownika
+
+| Zawartość słownika v6 | Zawartość słownika v7 |
+| --------------------- | --------------------- |
+| `autoFill: xxx`       | `fill: xxx`           |
+
+#### Przykład migracji
+
+**Przed (v6):**
+
+```typescript
+const content = {
+  key: "example",
+  autoFill: true, // Nadpisuje ten plik
+  content: {
+    title: "Hello World",
+  },
+};
+```
+
+**Po (v7):**
+
+```typescript
+const content = {
+  key: "example",
+  fill: true, // Nadpisuje ten plik
+  content: {
+    title: "Hello World",
+  },
+};
+```
+
+---
+
+## Notatki dotyczące migracji z v5 do v6
+
+Sprawdź [notatki dotyczące migracji z v5 do v6](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/releases/v6.md) po więcej informacji.
+
+---
+
+## Przydatne linki
+
+- [Referencja konfiguracji](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/configuration.md)
+- [Dokumentacja Middleware](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/next-intlayer/index.md)
+- [Typy TypeScript](https://github.com/aymericzip/intlayer/blob/main/packages/%40intlayer/types/src/index.ts)
+- [Wytyczne dotyczące plików cookie zgodne z RODO](https://gdpr.eu/cookies/)