@intlayer/docs 8.12.4 → 9.0.0-canary.10

package/docs/nl/intlayer_with_vite+vanilla.md

@@ -25,6 +25,7 @@ history:
   - version: 8.4.10
     date: 2026-03-23
     changes: "Initiële geschiedenis"
+author: aymericzip
 ---
 
 # Vertaal uw Vite- en Vanilla JS-website met Intlayer | Internationalisering (i18n)
@@ -79,28 +80,44 @@ Met Intlayer kunt u:
 
 Installeer de benodigde pakketten met npm:
 
+```bash packageManager="npm"
+npx intlayer-cli init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer-cli init --interactive
+```
+
+> de `--interactive` vlag is optioneel. Gebruik `intlayer-cli init` als je een AI-agent bent.
+
+> Dit commando detecteert uw omgeving en installeert de benodigde pakketten. Bijvoorbeeld:
+
 ```bash packageManager="npm"
 npm install intlayer vanilla-intlayer
 npm install vite-intlayer --save-dev
-npx intlayer init
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer vanilla-intlayer
 pnpm add vite-intlayer --save-dev
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer vanilla-intlayer
 yarn add vite-intlayer --save-dev
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer vanilla-intlayer
 bun add vite-intlayer --dev
-bun x intlayer init
 ```
 
 - **intlayer**
@@ -150,7 +167,13 @@ import { intlayer } from "vite-intlayer";
 
 // https://vitejs.dev/config/
 export default defineConfig({
-  plugins: [intlayer()],
+  plugins: [
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
+  ],
 });
 ```
 
@@ -411,12 +434,15 @@ Voeg eerst `intlayerProxy` toe aan uw Vite-configuratie:
 
 ```typescript {3,7} fileName="vite.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
 import { defineConfig } from "vite";
-import { intlayer, intlayerProxy } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 
 export default defineConfig({
   plugins: [
-    intlayerProxy(), // moet als eerste worden geplaatst
-    intlayer(),
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
   ],
 });
 ```
@@ -548,6 +574,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Babel-compiler'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 Werk uw `vite.config.ts` bij om de `intlayerCompiler`-plugin op te nemen:
 
 ```ts fileName="vite.config.ts"
@@ -557,7 +585,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // Voegt de compiler-plugin toe
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/nl/introduction.md

@@ -16,6 +16,7 @@ history:
   - version: 5.5.10
     date: 2025-06-29
     changes: "Init history"
+author: aymericzip
 ---
 
 # Intlayer Documentatie

package/docs/nl/packages/intlayer/comparePaths.md

@@ -0,0 +1,173 @@
+---
+createdAt: 2026-06-22
+updatedAt: 2026-06-22
+title: Documentatie voor de functie comparePaths | intlayer
+description: Bekijk hoe u de functie comparePaths gebruikt voor het intlayer-pakket
+keywords:
+  - comparePaths
+  - normalizePath
+  - actieve link
+  - navigatie
+  - Intlayer
+  - intlayer
+  - Internationalisatie
+  - Documentatie
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - packages
+  - intlayer
+  - comparePaths
+history:
+  - version: 9.0.0
+    date: 2026-06-22
+    changes: "Initiële documentatie"
+author: aymericzip
+---
+
+# Documentatie: Functie `comparePaths` in `intlayer`
+
+## Beschrijving
+
+De functie `comparePaths` vergelijkt twee URL's of paden op gelijkheid, waarbij het locale-segment, het protocol/host, de query-string, de hash en afsluitende schuine strepen (trailing slashes) worden genegeerd. Het is de aanbevolen manier om te bepalen of een navigatielink naar de huidige pagina verwijst — bijvoorbeeld om de actieve link te markeren — zonder dat u zelf (foutgevoelige) normalisatielogica hoeft te schrijven.
+
+Intern hergebruikt het [`getPathWithoutLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/nl/packages/intlayer/getPathWithoutLocale.md) om het locale-segment te verwijderen, zodat het uw geconfigureerde routeringsmodus en locales respecteert.
+
+Het pakket exporteert ook de onderliggende hulpmethode [`normalizePath`](#normalizepath), die het canonieke, locale-onafhankelijke pad retourneert dat wordt gebruikt voor de vergelijking.
+
+**Belangrijkste kenmerken:**
+
+- Locale-onafhankelijke vergelijking (`/nl/about` komt overeen met `/about`)
+- Werkt met zowel absolute URL's als relatieve paden
+- Negeert query-strings, hashes en afsluitende schuine strepen
+- Tolereert ontbrekende voorloopstrepen en lege waarden (genormaliseerd naar `/`)
+- Lichtgewicht — gebouwd bovenop `getPathWithoutLocale`
+
+---
+
+## Functiesignatuur
+
+```typescript
+comparePaths(
+  pathname: string,  // Vereist
+  href: string,      // Vereist
+  locales?: Locales[] // Optioneel
+): boolean
+
+normalizePath(
+  inputUrl: string,   // Vereist
+  locales?: Locales[] // Optioneel
+): string
+```
+
+---
+
+## Parameters
+
+- `pathname: string`
+  - **Beschrijving**: De eerste URL-tekenreeks of het pad om te vergelijken (meestal het huidige pad).
+  - **Type**: `string`
+  - **Vereist**: Ja
+
+- `href: string`
+  - **Beschrijving**: De tweede URL-tekenreeks of het pad om te vergelijken (meestal de `href` van een navigatielink).
+  - **Type**: `string`
+  - **Vereist**: Ja
+
+- `locales: Locales[]`
+  - **Beschrijving**: Optionele array van ondersteunde locales. Standaard ingesteld op de geconfigureerde locales in het project.
+  - **Type**: `Locales[]`
+  - **Vereist**: Nee (Optioneel)
+
+### Retourneert
+
+- **Type**: `boolean`
+- **Beschrijving**: `true` wanneer beide invoeren leiden tot hetzelfde locale-onafhankelijke pad, anders `false`.
+
+---
+
+## Voorbeeldgebruik
+
+### Basisgebruik
+
+```typescript codeFormat={["typescript", "esm", "commonjs"]}
+import { comparePaths } from "intlayer";
+
+comparePaths("/ru/path", "/path"); // true
+comparePaths("/ru/path/", "/path"); // true
+comparePaths("/ru/path", "/path/"); // true
+comparePaths("/ru/", "/"); // true
+comparePaths("/ru", "/"); // true
+comparePaths("ru/path", "/path"); // true
+comparePaths("", "/"); // true
+comparePaths("/ru", ""); // true
+comparePaths("/ru/path", "/other"); // false
+```
+
+### Absolute en relatieve URL's
+
+```typescript
+import { comparePaths } from "intlayer";
+
+comparePaths("https://example.com/ru/path", "/path"); // true
+```
+
+### De actieve navigatielink markeren
+
+```tsx
+import { comparePaths } from "intlayer";
+import { useLocation } from "react-router";
+
+const NavLink = ({ href, children }) => {
+  const { pathname } = useLocation();
+  const isActive = comparePaths(pathname, href);
+
+  return (
+    <a href={href} aria-current={isActive ? "page" : undefined}>
+      {children}
+    </a>
+  );
+};
+```
+
+---
+
+## normalizePath
+
+`normalizePath` retourneert het canonieke, locale-onafhankelijke pad dat wordt gebruikt door `comparePaths`. Het verwijdert het locale-segment, het protocol/host, de query-string en de hash, zorgt voor een enkele voorloopstreep, verwijdert eventuele afsluitende schuine strepen (behalve voor de root) en valt terug op `/` voor lege waarden.
+
+```typescript codeFormat={["typescript", "esm", "commonjs"]}
+import { normalizePath } from "intlayer";
+
+normalizePath("/ru/path"); // "/path"
+normalizePath("/ru/path/"); // "/path"
+normalizePath("ru/path"); // "/path"
+normalizePath("/ru/"); // "/"
+normalizePath("/ru"); // "/"
+normalizePath(""); // "/"
+normalizePath("https://example.com/ru/path"); // "/path"
+```
+
+---
+
+## Gerelateerde functies
+
+- [`getPathWithoutLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/nl/packages/intlayer/getPathWithoutLocale.md): Verwijdert het locale-segment van een URL of pad.
+- [`getPrefix`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/nl/packages/intlayer/getPrefix.md): Bepaalt de URL-prefix voor een gegeven locale.
+- [`getLocalizedUrl`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/nl/packages/intlayer/getLocalizedUrl.md): Genereert een gelokaliseerde URL voor een specifieke locale.
+
+---
+
+## TypeScript
+
+```typescript
+function normalizePath(inputUrl: string, locales?: Locales[]): string;
+
+function comparePaths(
+  pathname: string,
+  href: string,
+  locales?: Locales[]
+): boolean;
+```

package/docs/pl/CI_CD.md

@@ -19,6 +19,7 @@ history:
   - version: 5.5.10
     date: 2025-06-29
     changes: "Inicjalizacja historii"
+author: aymericzip
 ---
 
 # Automatyczne generowanie tłumaczeń w pipeline CI/CD

package/docs/pl/agent_skills.md

@@ -16,6 +16,7 @@ history:
   - version: 8.1.0
     date: 2026-02-09
     changes: "Historia początkowa"
+author: aymericzip
 ---
 
 # Umiejętności agenta

package/docs/pl/autoFill.md

@@ -28,12 +28,33 @@ history:
   - version: 5.5.10
     date: 2025-06-29
     changes: "Inicjalizacja historii"
+author: aymericzip
 ---
 
 # Tłumaczenia plików deklaracji wypełniania zawartości
 
 **Pliki deklaracji autouzupełniania** w Twoim CI to sposób na przyspieszenie procesu tworzenia oprogramowania.
 
+## Zrozumienie zachowania
+
+Polecenie `fill` zawiera dwa tryby:
+
+- **Complete**: Automatycznie wypełnia całą brakującą treść dla każdej lokalizacji i edytuje bieżący plik lub inny plik, jeśli jest określony. To znaczy, tryb complete pominiesz tłumaczenie istniejącej treści, jeśli jest już przetłumaczona.
+- **Review**: Automatycznie wypełnia **całą** treść dla każdej lokalizacji i generuje dla określonego pliku lub innego pliku, jeśli jest określony.
+
+Polecenie fill będzie przetwarzać wszystkie pliki deklaracji treści lokalizacji. To znaczy, nie będzie przetwarzać zdalnej treści z CMS. CMS zawiera własne zarządzanie tłumaczeniami.
+Jeśli używasz wtyczek takich jak `@intlayer/sync-json-plugin`, Intlayer przekształci pliki JSON w pliki deklaracji treści lokalizacji. To znaczy, będą przetwarzane przez polecenie `fill`.
+
+Nowo wygenerowane pliki zawierają instrukcję `filled` jako metadane słownika. Instrukcja ta będzie używana przez Intlayer do określenia, czy plik został automatycznie wypełniony, czy nie, i pominie ten plik z ponownego tłumaczenia, jeśli jest obecny.
+
+Intlayer będzie również uwzględniać następującą instrukcję do automatycznego wypełniania:
+
+- Z twojego pliku `.content.{ts|js|json}` → instrukcja `fill`
+- Z pliku konfiguracyjnego `.intlayer.config.ts` → instrukcja `dictionary.fill`
+- Będzie domyślnie ustawiona na `true` w przeciwnym razie
+
+W przypadku plików deklaracji treści dla poszczególnych lokalizacji instrukcja `true` zostanie zastąpiona przez `./{{fileName}}.fill.content.json`. Dzieje się tak, ponieważ plik deklaracji treści dla poszczególnych lokalizacji nie może otrzymać dodatkowej zlokalizowanej treści. Dlatego wygeneruje nowy plik, aby nie nadpisać istniejącego pliku.
+
 ## Domyślne zachowanie
 
 Domyślnie `fill` jest ustawione globalnie na `true`, co oznacza, że Intlayer automatycznie wypełni wszystkie pliki zawartości i edytuje sam plik. To zachowanie można dostosować na kilka sposobów:

package/docs/pl/benchmark/___NOTE.md

@@ -0,0 +1,101 @@
+---
+createdAt: 2024-03-07
+updatedAt: 2024-03-07
+title: Notatki z benchmarku
+description: Szczegółowe notatki i obserwacje z benchmarku frameworka i18n.
+keywords:
+  - benchmark
+  - i18n
+  - notatki
+  - porównanie
+slugs:
+  - doc
+  - benchmark
+  - note
+author:
+  name: Aymeric PINEAU
+  github: aymericzip
+---
+
+**gt-react** / **gt-next**
+
+Nie byłem w stanie przetestować gt-react / gt-next. Biblioteki nie są funkcjonalne i łamią aplikację.
+
+- Nie byłem w stanie przetestować reaktywności aplikacji.
+- Tłumaczenia nie są renderowane; otrzymuję błąd `Error: <T> used on the client-side outside of <GTProvider>`, co wydaje się być błędem w bibliotece.
+- Podczas implementacji **gt-tanstack-start-react**, natknąłem się na problem z biblioteką: `does not provide an export named 'printAST' - @formatjs/icu-messageformat-parser`, co powodowało, że aplikacja się łamała. Po zgłoszeniu tego problemu, opiekun naprawił go w ciągu 24 godzin.
+- Ta biblioteka wymaga zależności od serwera General Translation do tłumaczenia. Nawet jedna próba tłumaczenia zwróciła błąd: `Quota Exceeded, please upgrade your plan`. Ryzyko blokady dostawcy jest wysokie.
+- Te biblioteki używają antywzorca poprzez funkcję `initializeGT()`, które blokują bundle od czystego tree-shakingu.
+- Dla implementacji nextjs, biblioteka blokuje statyczne renderowanie stron Next.js.
+
+**Lingo.dev**
+
+- Ciężka zależność od serwera lingo.dev do generowania tłumaczeń. Nawet jeśli zawierają bardziej hojny bezpłatny poziom niż General Translation, ryzyko blokady dostawcy jest wysokie.
+- Konfiguracja nie była prosta. Musiałem reverse-inżynierować ich kod i wymuszać przesłanie zmiennej środowiskowej, aby to zadziałało.
+- Ich CLI jest bugowy i zwykł przepisywać plik konfiguracyjny za każdym razem, gdy go używałem.
+- Kompilator brakował prawie 40% przetłumaczonej zawartości. Musiałem przepisać wszystkie `.map` na płaskie bloki komponentów, aby to zadziałało.
+- Spotkałem się z problemami reaktywności z biblioteką. Przy zmianie lokali musiałem wymusić ponowne renderowanie dostawcy, aby to zadziałało.
+- Przy przebudowie czasami losowo usuwało wszystkie wygenerowane tłumaczenia bez żadnego powodu.
+
+**next-translate**
+
+- Dla aplikacji Next.js, ta biblioteka była wielkim odkryciem; podejście jest niezwykle dobrze przemyślane i łatwe do wdrożenia, a wyniki są imponujące. Zysk w porównaniu do innych bibliotek używających składni `t()` jest znaczący, takiej jak **next-intl** lub **next-i18next**.
+- Ta biblioteka używa podejścia transformacji czasu budowania z `react-translate-plugin`: przepisuje strony i wstawia pobieranie zawartości za pomocą `getStaticProps` lub `getServerSideProps` poprzez loader Webpack / Turbopack. Rezultatem jest to, że nigdy nie pobierasz zawartości z innych lokali.
+- Dla namespacing, wybieranie namespaces na poziomie konfiguracji jest również dobrze przemyślane: możesz definiować namespaces dla każdej strony lub trasy. Czyni to utrzymanie znacznie łatwiejszym niż główne alternatywy, takie jak **next-intl** lub **next-i18next**.
+- Ta biblioteka obsługuje zarówno Webpack jak i Turbopack, komponenty klienckie i serwerowe, oraz Pages i App Router.
+- Nawet jeśli to rozwiązanie ma >6 lat, biblioteka jest nadal aktywnie utrzymywana.
+- Nie ma strony internetowej i dokumentacji online; są dostępne tylko na GitHub. Lubię odkrywać świetne biblioteki i naprawiać problemy w czystym podejściu, bez dodatkowych warstw marketingu.
+- Wszystkie stałe są transformowane w funkcje, co prowadzi do antywzorca. Składnia taka jak `const t = useTranslation('xx')` + `<>{t('xx.xx')}</>` wprowadza niepotrzebną złożoność i prowadzi do overhead wykonywania JavaScript.
+- Biblioteka blokuje statyczne renderowanie stron Next.js.
+
+**Tolgee**
+
+- Implementacja była trudna do uzyskania, szczególnie ponieważ biblioteka nie zapewnia bezpieczeństwa typów. Aby wykryć błędne klucze, musiałem ręcznie przepisać logikę bezpieczeństwa typów i ponownie użyć własnej implementacji funkcji `getTranslation`.
+- Ta biblioteka obsługuje zarówno Webpack jak i Turbopack, komponenty klienckie i serwerowe, oraz Pages i App Router.
+- Nie ma strony internetowej i dokumentacji online; są dostępne tylko na GitHub.
+- Na tanstack start spotkałem się również z problemami reaktywności z biblioteką. Przy zmianie lokali musiałem wymusić ponowne renderowanie dostawcy. Musiałem zasubskrybować zdarzenie zmiany lokali, aby to zadziałało podczas ładowania strony w innej lokali.
+- Dla implementacji nextjs, biblioteka blokuje statyczne renderowanie stron Next.js.
+- Spotkałem się również z problemami z DevTools dostarczonym przez bibliotekę. Zwykł rejestrować błędy w konsoli po stronie serwera.
+
+**next-translate**
+
+- Nawet jeśli to rozwiązanie ma >6 lat, biblioteka jest nadal aktywnie utrzymywana.
+- Ta biblioteka używa podejścia transformacji czasu budowania z `react-translate-plugin`: przepisuje strony i wstawia pobieranie zawartości za pomocą `getStaticProps` lub `getServerSideProps`. Rezultatem jest to, że nigdy nie pobierasz zawartości z innych lokali.
+
+**next-intl** / **use-intl** / **next-i18next** / **react-i18next** / **next-international**
+
+- Takie same zalety i wady dla wszystkich tych bibliotek, które używają składni `t()`.
+- Optymalizacje są możliwe, ale niezwykle czasochłonne. Dobre praktyki nie są wyraźnie wyróżnione, i może być łatwe dla agentów lub juniorskich deweloperów, aby zaszkodzić wydajności aplikacji przez złe praktyki. Szczególnie przy użyciu namespacing plus dynamiczne ładowanie, zachowanie bezpieczeństwa typów i wiedza dokładnie, który namespace powinien być uwzględniony na której stronie jest koszmarem.
+- Wszystkie te biblioteki oferują podobne podejście, dobrze połączone z systemem reaktywności React. Ale `next-intl` oferuje dodatkowe funkcje, takie jak obsługa middleware, formatery, itp.
+- Formaty wiadomości różnią się między bibliotekami. `next-intl` używa formatu ICU MessageFormat, podczas gdy `i18next` używa własnego formatu.
+- **next-intl** jest znacznie lżejszym rozwiązaniem niż **i18next**, ale pozostaje ciężkie i słabo zoptymalizowane.
+- **next-intl** zwykł blokować statyczne renderowanie stron Next.js. Zapewnia funkcję naprawy o nazwie `setRequestLocale()`, która nie była łatwa do zrozumienia przyczyny problemu lub jak go naprawić. Ten problem wydaje się został rozwiązany i nie blokuje już statycznego renderowania dla scentralizowanej zawartości, takiej jak `en.json` / `fr.json` / `es.json` / itp. Należy pamiętać, że nadal blokuje statyczne renderowanie, gdy zawartość jest ograniczona do namespaces, takich jak `en/shared.json` / `fr/shared.json` / `es/shared.json` / itp.
+- Oba rozwiązania nie oferują sposobu na tłumaczenie synchronicznych komponentów serwerowych, takich jak navbar design-system, stopka, itp. W rezultacie wszystkie komponenty muszą być tłumaczone po stronie klienta.
+- Wszystkie stałe są transformowane w funkcje, co prowadzi do antywzorca. Składnia taka jak `const t = useTranslation('xx')` + `<>{t('xx.xx')}</>` wprowadza niepotrzebną złożoność i prowadzi do overhead wykonywania JavaScript.
+- **next-international** zawiera funkcję `scopedT()`, która pozwala na tłumaczenie zawartości w określonym namespace, co utrudnia proces refaktoringu do celów optymalizacji. Ale ponieważ nie ma sposobu na podział json w namespaces, ta funkcja jest raczej bezużyteczna. Poprawia tylko DX, ale nie ma wpływu na rozmiar bundle.
+
+**Lingui**
+
+- Rozsądna wydajność i wpływ, z dobrym poszanowaniem najlepszych praktyk.
+- Implementacja jest złożona dla funkcji, które nie są komponentami strony, takimi jak Next.js `generateMetadata`. Musisz stworzyć nową instancję i18n, wybrać wiadomości do załadowania, a następnie je przetłumaczyć.
+- Przepływ może być nieco złożony do zrozumienia przy pierwszej implementacji.
+- Myląca składnia, np. `t()`, `t''`, `i18n.t()`, `<Trans>`. Wiedza, które praktyki należy używać w aplikacji, nie jest intuicyjna.
+
+**Wuchale**
+
+- Świetne podejście próbujące automatyzować proces ekstrakcji i tłumaczenia bez jakiejkolwiek składni `t()`.
+- Rozwiązanie Svelte-first. Adaptacja React biblioteki nie jest tak dojrzała jak wersja Svelte. Reaktywność aplikacji React nie zadziałała. Musiałem wymusić ponowne renderowanie dostawcy przy zmianie lokali, używając niestandardowego stanu `isMounted()/effect` aby to zadziałało.
+- Używa antywzorca dla funkcji inicjalizacji, aby załadować się przed inicjalizacją routera.
+
+**Paraglide**
+
+- Teoretycznie dla aplikacji zawierających wiele lokali, Paraglide zawiera wszystkie wiadomości w bundle. Nie ma sposobu na dynamiczne ładowanie wiadomości. Nawet jeśli promują optymalizacja `tree-shaking`, biblioteka głównie przenosi problem bundlowania gdzie indziej. Przyszła poprawa dla dynamicznego ładowania wydaje się niemożliwa biorąc pod uwagę architekturę biblioteki. Użycie dynamicznego ładowania prowadziłoby do tysięcy żądań do serwera.
+- W praktyce, wynik używania Paraglide jest jeszcze gorszy niż oczekiwany. Na nextjs (Turbopack) jak dla tanstack start (Rolldown), bundler nawet nie tree shake wiadomości. W rezultacie, ostateczny rozmiar bundle zawiera zawartość ze wszystkich stron i wszystkich lokali.
+- Złożony przepływ używający plików deklaracji JSON jako źródła prawdy, plus generacja plików wiadomości w czasie budowania, następnie ręczne importy w każdym komponencie.
+- Wszystkie stałe są transformowane w funkcje, co prowadzi do antywzorca. Składnia taka jak `import * as m from '@/messages'` + `<>{m.myContent()}</>` wprowadza niepotrzebną złożoność i prowadzi do overhead wykonywania JavaScript.
+- W porównaniu z innymi rozwiązaniami, które używają react context do efektywnego pobierania aktualnej lokali do renderowania zawartości, Paraglide będzie czytać dla każdego węzła zawartości zaimportowanej lokalę z localeStorage / cookie itp. Prowadzi to do wykonywania niepotrzebnej logiki.
+
+**react-intl**
+
+- Wydajna implementacja, zrobiona przez zespół Format.js.
+- Myląca DX przy użyciu `const intl = useIntl()` + `intl.formatMessage({ id: "xx.xx" })` wprowadza niepotrzebną złożoność, prowadzi do overhead wykonywania JavaScript i łączy globalną instancję i18n ze wszystkimi węzłami komponentów.

package/docs/pl/benchmark/___nextjs.md

@@ -0,0 +1,198 @@
+---
+createdAt: 2026-04-20
+updatedAt: 2026-04-21
+title: Najlepsze rozwiązanie i18n dla Next.js w 2026 - Raport benchmarku
+description: Porównaj biblioteki internacjonalizacji Next.js takie jak next-intl, next-i18next i Intlayer. Szczegółowy raport wydajności dotyczący rozmiaru bundle, wycieków i reaktywności.
+keywords:
+  - benchmark
+  - i18n
+  - intl
+  - nextjs
+  - wydajność
+  - intlayer
+slugs:
+  - doc
+  - benchmark
+  - nextjs
+author:
+  name: Aymeric PINEAU
+  github: aymericzip
+history:
+  - version: 8.7.5
+    date: 2026-01-06
+    changes: "Init benchmark"
+---
+
+# Raport benchmarku bibliotek i18n dla Next.js w 2026
+
+Ta strona jest raportem benchmarku dla rozwiązań i18n dla Next.js.
+
+## Spis treści
+
+<Toc/>
+
+## Interaktywny benchmark
+
+<I18nBenchmark framework="nextjs" vertical/>
+
+## Referencja wyników:
+
+<ClickToOpenIframe
+src="https://intlayer.org/markdown?url=https%3A%2F%2Fraw.githubusercontent.com%2Fintlayer-org%2Fbenchmark-i18n%2Fmain%2Freport%2Fscripts%2Fsummarize-nextjs.md"
+width="100%"
+height="600px"
+style="border:none;"
+/>
+
+> [Patrz kompletne dane benchmarku](https://intlayer.org/markdown?url=https%3A%2F%2Fraw.githubusercontent.com%2Fintlayer-org%2Fbenchmark-i18n%2Fmain%2Freport%2Fscripts%2Fsummarize-nextjs.md)
+
+## Wstęp
+
+Rozwiązania internacjonalizacyjne są bibliotekami o dużym wpływie na aplikację. Głównym ryzykiem jest załadowanie zawartości wszystkich stron i wszystkich języków dla pojedynczej przeglądanej strony.
+
+Wraz z rozwojem aplikacji rozmiar bundle ewoluuje wykładniczo, co może znacząco spowolnić wydajność aplikacji.
+
+Jako przykład, dla najgorszych uczniów, po internacjonalizacji strona może skończyć się prawie 4 razy bardziej objętościowa.
+
+Innym wpływem rozwiązań internacjonalizacyjnych jest spowolnienie rozwoju. Transformowanie komponentów i organizowanie zawartości we wszystkich językach jest czasochłonne.
+
+Problem jest złożony, wiele rozwiązań pojawiło się aby rozwiązać problem i18n. Niektóre rozwiązania skupiają się na DX, inne na wydajności, inne na skalowalności, itp.
+
+Intlayer jest rozwiązaniem próbującym optymalizować wszystkie te aspekty.
+
+## Testuj swoją aplikację
+
+Aby wykryć te problemy, mam skonfigurowany bezpłatny skaner, który możesz przetestować [tutaj](https://intlayer.org/i18n-seo-scanner).
+
+## Problematyka
+
+Istnieją dwa główne aspekty aby ograniczyć wpływ wielojęzycznej aplikacji na bundle aplikacji:
+
+- Podziel swoje JSON (lub zawartość) na wiele plików / zmiennych / namespaces aby umożliwić bundlerowi tree-shake zawartość nieużywaną na stronie
+- Dynamicznie załaduj zawartość strony tylko w języku strony
+
+Zrozumienie ograniczeń technicznych dla tych podejść:
+
+**Dynamiczne ładowanie**
+
+Nawet jeśli deklarujesz swoje trasy jako `[locale]/page.tsx`, czy to z Webpack czy Turbopack, i mimo że `getStaticParams` jest zdefiniowany, bundler nie traktuje `locale` jako zmiennej statycznej. To oznacza, że bundler załaduje zawartość wszystkich języków dla każdej strony. Jedyną opcją aby ograniczyć ten problem jest załadowanie zawartości poprzez dynamiczny import (np. `import('./locales/${locale}.json')`).
+
+To co się dzieje podczas budowania, to że Next.js generuje plik JS (bundle) dla każdego języka (np. `./locales_fr_12345.js`). Następnie po wysłaniu witryny do klienta, gdy strona jest wykonywana, to przeglądarka zmieni się w wykonanie dodatkowego żądania HTTP, żądając wymaganego pliku JS (np. `./locales_fr_12345.js`).
+
+> Innym sposobem na odpowiedź na ten sam problem jest użycie metody `fetch()` aby dynamicznie żądać pliku JSON. To jest przypadek `Tolgee` poprzez umieszczenie JSON w folderze `/public` lub `next-translate`, które opierają się na funkcji `getStaticProps` aby załadować zawartość. Ale przepływ pozostaje taki sam, przeglądarka wykona dodatkowe żądanie HTTP aby załadować asset.
+
+**Podział zawartości**
+
+Jeśli używasz składni takiej jak `const t = useTranslation()` + `t('my-object.my-sub-object.my-key')`, JSON musi być w całości załadowany do bundle, aby następnie być parsowany przez bibliotekę aby wydedukować wartość klucza. Ale to oznacza, że duża część zawartości będzie załadowana w bundle, choć nieużywana na stronie.
+
+Aby odpowiedzieć na ten problem, niektóre biblioteki sugerują deklarowanie ręcznie dla każdej strony, które namespaces powinny być załadowane. To jest przypadek `next-i18next`, `next-intl`, `lingui`, `next-translate`, `next-international`.
+
+W porównaniu, `Paraglide` proponuje dodanie dodatkowego kroku, przed budowaniem aby transformować JSON w płaską zmienną, taką jak `const en_my_var = () => 'my value'`. To pozwala (teoretycznie) tree-shake zawartość nieużywaną na stronie. Ale zobaczymy, ta metoda nie jest bez kompromisów.
+
+Na koniec, `Intlayer` proponuje optymalizację w czasie budowania, pozwalającą na zastąpienie użycia `useIntlayer('my-key')` i bezpośrednie dołączenie odpowiadającej zawartości.
+
+## Metodologia
+
+Dla tego benchmarku porównaliśmy następujące biblioteki:
+
+- `Base App` (No i18n library)
+- `next-intlayer` (v8.7.5)
+- `next-i18next` (v16.0.5)
+- `next-intl` (v4.9.1)
+- `@lingui/core` (v5.3.0)
+- `next-translate` (v3.1.2)
+- `next-international` (v1.3.1)
+- `@inlang/paraglide-js` (v2.15.1)
+- `tolgee` (v7.0.0)
+- `@lingo.dev/compiler` (v0.4.0)
+- `wuchale` (v0.22.11)
+- `gt-next` (v6.16.5)
+
+Użyłem frameworka `Next.js` w wersji `16.2.4` z trybem `app router`.
+
+Stworzyłem wielojęzyczną aplikację z **10 stronami**, w **10 językach**.
+
+I porównałem **4 strategie ładowania**:
+
+| Strategi              | Bez Namespaces (Global)                        | Z Namespaces (Scoped)                                                |
+| :--------------------- | :------------------------------------------------ | :---------------------------------------------------------------------- |
+| **Ładowanie Static**  | **Static** : Wszystko w pamięci przy uruchomieniu.        | **Scoped Static** : Podzielone na namespace, wszystko załadowane przy uruchomieniu.   |
+| **Ładowanie Dynamic** | **Dynamic** : Ładowanie na żądanie przez lokalę. | **Scoped Dynamic** : Ładowanie granularne przez namespace i lokalę. |
+
+## Streszczenie strategii
+
+- **Static** : Proste, bez opóźnień sieciowych po załadowaniu początkowym. Wadą : wysoki rozmiar bundle.
+- **Dynamic** : Zmniejsza początkowy waga (lazy-loading). Idealne dla dużej liczby lokali.
+- **Scoped Static** : Pozwala na czystą organizację kodu (logiczne separacja) bez dodatkowego kosztu złożonych żądań sieciowych.
+- **Scoped Dynamic** : Optymalne podejście do _Code Splitting_ i wydajności. Minimalizuje obciążenie pamięci ładując tylko niezbędne dla bieżącego widoku i aktywnej lokali.
+
+## Szczegóły wyników
+
+### 1 - Rozwiązania do uniknięcia
+
+Pewne rozwiązania takie jak `gt-next` lub `lingo.dev` są wyraźnie rozwiązaniami do uniknięcia. Te rozwiązania integrują kombo blokady dostawcy + zatrucie bazy kodu. I górą wszystkiego jest to, że pomimo wielu godzin próby ich implementacji, nigdy mi się nie udało je uruchomić. Zarówno dla Tanstack start jak i Next.js.
+
+Lista napotkaných problemów:
+
+**(General Translation)** (`gt-next@6.16.5`):
+
+- Dla aplikacji 110kb, `gt-react` dodaje do niej ponad 440kb dodatkowego.
+- `Quota Exceeded, please upgrade your plan`, od pierwszego budowania z rozwiązaniem general translation.
+- Tłumaczenia nie są renderowane; otrzymuję błąd `Error: <T> used on the client-side outside of <GTProvider>`, co wydaje się być błędem w bibliotece.
+- Podczas implementacji **gt-tanstack-start-react**, natknąłem się na [problem](https://github.com/generaltranslation/gt/issues/1210#event-24510646961) z biblioteką: `does not provide an export named 'printAST' - @formatjs/icu-messageformat-parser`, co powodowało, że aplikacja się łamała. Po zgłoszeniu tego problemu, opiekun naprawił go w ciągu 24 godzin.
+- Biblioteka blokuje statyczne renderowanie stron Next.js.
+
+**(Lingo.dev)** (`@lingo.dev/compiler@0.4.0`):
+
+- Przywłaszczony limit AI, całkowicie blokujący budowanie. Jest wtedy niemożliwe pushowanie do produkcji bez płacenia.
+- Kompilator brakował prawie 40% przetłumaczonej zawartości. Musiałem przepisać wszystkie `.map` na płaskie bloki komponentów aby to zadziałało.
+- Ich CLI jest bugowy i zwykł resetować plik konfiguracyjny bez powodu.
+- Przy budowaniu, całkowicie wymazywał wygenerowane JSON gdy była dodana nowa zawartość. W wyniku, masz tylko 3 klucze usuwające >300 istniejących kluczy.
+
+### 2 - Rozwiązania eksperymentalne
+
+**(Wuchale)** (`wuchale@0.22.11`):
+
+Ideą `Wuchale` jest interesująca, ale nie jest jeszcze na etapie żywotnego rozwiązania. Napotkałem problemy reaktywności z biblioteką i musiałem wymusić ponowne renderowanie dostawcy aby uruchomić aplikację. Dokumentacja jest również stosunkowo niejasna, utrudniając przyjęcie.
+
+**(Paraglide)** (`@inlang/paraglide-js@2.15.1`):
+
+`Paraglide` jest rozwiązaniem oferującym innowacyjne i dobrze przemyślane podejście. Niemniej jednak, w kontekście mojego benchmarku, widać, że tree-shaking, który sprzedają ich firma, nie działa ani dla mojej implementacji Next.js, ani dla Tanstack start. Przepływ i DX jest również bardziej złożony niż inne rozwiązania. I osobiście nie lubię faktu, że muszę przeregenerować pliki JS przed każdym pushowaniem, tworząc ciągłe ryzyko konfliktów między deweloperami poprzez ich PR. Wreszcie, rozwiązanie wydaje się bardziej skupiać na Vite niż na Next.js.
+
+### 3 - Rozwiązania 'ok'
+
+**(Tolgee)** (`tolgee@7.0.0`):
+
+`Tolgee` jest rozwiązaniem odpowiadającym różnym problemom wspominanym wcześniej. Ale znalazłem przyjęcie rozwiązania bardziej złożonym niż inne rozwiązania proponujące podobne podejścia. Rozwiązanie nie proponuje typesafety. To czyni detektywę brakujących kluczy przy kompilacji znacznie bardziej złożoną. Musiałem owrappować funkcje Tolgee własnymi aby dodać detektywę brakujących kluczy.
+
+**(Next Intl)** (`next-intl@4.9.1`):
+
+`next-intl` jest najmodniejszym rozwiązaniem i również najbardziej wypromowanym przez agentów AI, ale moim zdaniem słusznie. Get-started jest dość prosty. Ale w praktyce, proces optymalizacji aby ograniczyć wyciek jest dość złożony. Similarly, współistnienie dynamicznego ładowania + namespacing + typescript types znacznie spowalnia rozwój. Ponadto biblioteka jest dość ciężka (~13kb dla `NextIntlClientProvider` + `useTranslations` hook, co jest >2x bardziej ciężkie niż `next-intlayer`). **next-intl** zwykł blokować statyczne renderowanie stron Next.js. Zapewnia funkcję naprawy o nazwie `setRequestLocale()`. Ten problem wydaje się został częściowo rozwiązany dla scentralizowanej zawartości takich jak `en.json` / `fr.json` / itp. Ale rozwiązanie nadal blokuje statyczne renderowanie gdy zawartość jest ograniczona do namespaces takimi jak `en/shared.json` / `fr/shared.json` / `es/shared.json` / itp.
+
+**(Next I18next)** (`next-i18next@16.0.5`):
+
+`next-i18next` jest prawdopodobnie najpopularniejszym rozwiązaniem faktem, że to była pierwsza rozwiązanie, które pojawiło się aby odpowiedzieć na potrzeby internacjonalizacji aplikacji Javascript. To rozwiązanie również proponuje szeroki zestaw pluginów społeczności aby odpowiedzieć na pewne problemy. Niemniej jednak, to rozwiązanie pokazuje dokładnie takie same czarne punkty co `next-intl`. Ponadto biblioteka jest szczególnie ciężka (~18kb dla `I18nProvider` + `useTranslation` hook, co jest 3x bardziej ciężkie niż `next-intlayer`).
+Ponadto formaty wiadomości różnią się między bibliotekami. `next-intl` używa formatu ICU MessageFormat, podczas gdy `i18next` używa własnego formatu.
+
+**(Next International)** (`next-international@1.3.1`):
+
+`next-international` jest rozwiązaniem odpowiadającym również różnym problemom wspominanym wcześniej, ale nie proponuje znaczącej różnicy w stosunku do `next-intl` lub nawet `next-i18next`. Rozwiązanie zawiera funkcję `scopedT()`, która pozwala na tłumaczenie zawartości w określonym namespace. Niemniej jednak, użycie tej funkcji nie ma czysto i po prostu żadnego wpływu na rozmiar bundle.
+
+**(Lingui)** (`@lingui/core@5.3.0`):
+
+`Lingui` jest rozwiązaniem dla którego słyszałem wiele dobrego. Ale osobiście znalazłem przepływ bazujący na wykonaniu poleceń `lingui extract` / `lingui compile` bardziej złożonym niż inne podejścia, bez znaczącej przewagi. Zauważyłem również brak harmonii między składniami które noszą AI do zamieszania. (np. `t()`, `t''`, `i18n.t()`, `<Trans>`)
+
+### 4 - Moje rekomendacje
+
+**(Next Translate)** (`next-translate@3.1.2`):
+
+`next-translate` jest tutaj moją główną rekomendacją dla tych, którzy lubią użycie funkcji `t()` do tłumaczenia zawartości. To rozwiązanie oferuje eleganckie podejście poprzez `next-transalte-plugin`, optymalizując ładowanie namespaces poprzez `getStaticProps` poprzez loader Webpack / Turbopack. To również najprostsze rozwiązanie ze wszystkich (~2.5kb tylko). Do namespacing, wybieranie namespaces na poziomie konfiguracji jest również dobrze przemyślane: możesz definiować namespaces dla każdej strony lub trasy. Czyni to utrzymanie znacznie łatwiejszym niż główne alternatywy, takie jako **next-intl** lub **next-i18next**. Niemniej jednak zauważyłem, że w wersji `3.1.2`, budowanie w statycznym renderowaniu nie działa. Next.js fallback wtedy na dynamiczne renderowanie.
+
+**(Intlayer)** (`next-intlayer@8.7.5`):
+
+Na koniec, nie będę osobiście sądził `next-intlayer`, z powodu obiektywności, biorąc pod uwagę, że jest to moje własne rozwiązanie.
+
+### Notatka personalna
+
+Ta notatka jest personalna i nie ma wpływu na wyniki benchmarku. Niemniej jednak, w świecie i18n widzimy wyraźny konsensus, którym jest użycie składni takiej jak `const t = useTranslation('xx')` + `<>{t('xx.xx')}</>` do tłumaczenia zawartości.
+Niemniej jednak, w kontekście aplikacji React, iniekcja funkcji w formie `ReactNode` jest moim zdaniem antywzorem. Ponadto, to wprowadza dodatkową złożoność, którą można uniknąć, i overhead wykonywania JavaScript (chociaż niezauważalny).