@intlayer/docs 8.12.5-canary.0 → 9.0.0-canary.11

package/docs/nl/releases/v9.md

@@ -0,0 +1,358 @@
+---
+createdAt: 2026-06-14
+updatedAt: 2026-06-30
+title: Nieuwe Intlayer v9 - Wat is er nieuw?
+description: Ontdek wat er nieuw is in Intlayer v9. Introductie van drop-in compatibiliteitspakketten voor populaire i18n-bibliotheken, ondersteuning voor Verzamelingen en Varianten, en zelf hosten via Docker Compose.
+keywords:
+  - Intlayer
+  - Compatibility
+  - Migration
+  - Collections
+  - Variants
+  - CMS SDK
+  - Self-Hosting
+  - Docker
+  - i18next
+  - next-intl
+  - vue-i18n
+slugs:
+  - doc
+  - releases
+  - v9
+author: aymericzip
+---
+
+# Nieuwe Intlayer v9 - Wat is er nieuw?
+
+Welkom bij Intlayer v9! Deze grote release markeert een enorme mijlpaal in het vereenvoudigen van het migratiepad naar Intlayer met **Compat-adapterpakketten** voor grote i18n-bibliotheken (`react-i18next`, `next-intl`, `vue-i18n`, enz.) en voegt ondersteuning toe voor rijke inhoudsstructuren: **Verzamelingen** en **Varianten**.
+
+## Inhoudsopgave
+
+<TOC levels={[2]} maxDepth={1} />
+
+---
+
+## Compat-adapterpakketten
+
+Migreren naar Intlayer vanuit populaire i18n-bibliotheken is nu eenvoudiger dan ooit. We hebben vijf compatibiliteitspakketten gemaakt die exact dezelfde publieke API's blootstellen als standaard i18n-bibliotheken, maar al het vertaalwerk tijdens uitvoering delegeren aan Intlayer.
+
+### Dezelfde publieke API blootstellen met strikte typering
+
+Door imports te vervangen, profiteert u van alle voordelen van Intlayer (inclusief compilatietijd type-veiligheid ten opzichte van uw werkelijke woordenboeken) met minimale codewijzigingen:
+
+- `@intlayer/i18next`
+- `@intlayer/react-i18next`
+- `@intlayer/next-intl`
+- `@intlayer/react-intl`
+- `@intlayer/next-i18next`
+- `@intlayer/vue-i18n`
+- `@intlayer/lingui`
+
+Wijzig bijvoorbeeld eenvoudig:
+
+```ts
+import { useTranslation } from "react-i18next";
+```
+
+naar:
+
+```ts
+import { useTranslation } from "@intlayer/react-i18next";
+```
+
+Uw sleutels worden nu **strikt getypeerd** op basis van uw Intlayer-woordenboeken, wat volledige dot-pad-autoaanvulling biedt in uw IDE!
+
+### Bundler-aliasplugins (Vite, Next.js, Turbopack)
+
+Om te migreren zonder alle importstatements handmatig te herschrijven, bevat elk compat-adapterpakket een **aangepaste bundler-plugin** (Vite of Next.js) onder het `/plugin`-subpad.
+
+Deze plugins herschrijven automatisch bestaande imports (bijv. `react-i18next` of `next-intl`) naar hun `@intlayer/*`-equivalenten tijdens het bouwen.
+
+#### Next.js (Webpack / Turbopack) Voorbeeld
+
+Gebruik in plaats van `withIntlayer` de compat-plugin om uw Next.js-configuratie te wikkelen:
+
+```ts fileName="next.config.ts"
+import { createNextI18nPlugin } from "@intlayer/next-i18next/plugin";
+import type { NextConfig } from "next";
+
+const withIntlayer = createNextI18nPlugin();
+const nextConfig: NextConfig = {};
+
+export default withIntlayer(nextConfig);
+```
+
+#### Vite (React, Vue, Solid, Svelte) Voorbeeld
+
+```ts fileName="vite.config.ts"
+import vueI18nVitePlugin from "@intlayer/vue-i18n/plugin";
+
+export default defineConfig({
+  plugins: [vueI18nVitePlugin()],
+});
+```
+
+---
+
+## Gedeelde runtime-resolver
+
+Alle compat-adapters routeren vertaalresolutie nu via één sterk geoptimaliseerde runtime-parser: `@intlayer/core/messageFormat`.
+
+- **Berichtinterpolatie**: Verwerkt standaard `{{var}}` (witruimte & dot-paden), ICU-geformatteerde argumenten (`{v, number, percent}` enz.) en gewone `{var}`-sjablonen.
+- **Berichtknooppuntresolver**: Verwerkt geneste knooppunten: `insert()`, `plural()` (CLDR meervoudsregels), `enu()` (opsomming), `gender()`, HTML-tags, arrays en aanroepbare functieknooppunten.
+- **Getokeniseerde tagparser**: Ondersteunt inline XML/HTML-tags en genummerde tags (bijv. `<1>children</1>`) voor rijke-tekstweergave zonder extra configuratie.
+
+---
+
+## Functiespecificaties: Verzamelingen en varianten
+
+Intlayer v9 gaat verder dan statische sleutel-waardeparen en stelt woordenboeken in staat dynamische layoutstructuren te declareren die end-to-end volledig getypeerd zijn.
+
+### 1. Verzamelingen
+
+Definieer een door CMS beheerde lijst met geordende items (bijv. FAQ's, producten of bloglijsten). Elk item bevindt zich in een eigen `.content.ts`-bestand met dezelfde `key` en een `item`-nummer:
+
+```ts fileName="faq.1.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+export default {
+  key: "faq",
+  item: 1,
+  content: {
+    question: t({ en: "What is Intlayer?", fr: "Qu'est-ce qu'Intlayer ?" }),
+    answer: t({ en: "An i18n toolkit.", fr: "Une boîte à outils i18n." }),
+  },
+} satisfies Dictionary;
+```
+
+```ts fileName="faq.2.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+export default {
+  key: "faq",
+  item: 2,
+  content: {
+    question: t({ en: "Is it free?", fr: "Est-ce gratuit ?" }),
+    answer: t({ en: "Yes, open-source.", fr: "Oui, open-source." }),
+  },
+} satisfies Dictionary;
+```
+
+#### Gebruik:
+
+```ts
+// Alle items als array ophalen
+const allFaqs = useIntlayer("faq"); // -> { question: string, answer: string }[]
+
+// Eén item ophalen op index
+const faq = useIntlayer("faq", { item: 2 }); // -> { question: string, answer: string }
+```
+
+### 2. Varianten
+
+Lever A/B-tests, seizoensgebonden koppen, functievlaggen of aangepaste landingspagina's:
+
+#### Tekstvarianten (bijv. A/B-testen)
+
+```ts fileName="hero.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+export default {
+  key: "hero-banner",
+  variant: "default",
+  content: {
+    control: t({ en: "Welcome", fr: "Bienvenue" }),
+    black_friday: t({ en: "Shop now", fr: "Acheter maintenant" }),
+  },
+} satisfies Dictionary;
+```
+
+#### Gebruik:
+
+```ts
+const banner = useIntlayer("hero-banner", { variant: "black_friday" });
+```
+
+#### Objectvarianten (bijv. Dynamische records)
+
+```ts fileName="product.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+export default {
+  key: "product-copy",
+  variant: {
+    id: "prod_123",
+    category: "books",
+  },
+  content: {
+    title: t({ en: "Clean Code", fr: "Code Propre" }),
+  },
+} satisfies Dictionary;
+```
+
+#### Gebruik:
+
+```ts
+// Haalt alleen het gevraagde record dynamisch op (vereist Suspense)
+const product = useIntlayer("product-copy", {
+  variant: { id: "prod_123", category: "books" },
+});
+```
+
+---
+
+## Dynamisch laden en bundel-optimalisaties
+
+Om bundels extreem klein te houden, ondersteunt Intlayer v9 dynamisch lui laden.
+
+Stel `importMode` in op `'dynamic'` of `'fetch'` in uw configuratie:
+
+```ts fileName="intlayer.config.ts"
+export default {
+  dictionary: {
+    importMode: "dynamic", // "static" | "dynamic" | "fetch"
+  },
+};
+```
+
+Tijdens het bouwen scannen `@intlayer/swc` en `@intlayer/babel` uw bestanden en vervangen `useIntlayer`/`getIntlayer`-aanroepen door tree-shakeable wrappers (`useDictionary`/`useDictionaryDynamic`). Alleen de inhoud die vereist is voor het geselecteerde verzamelingsitem, de variant of de taal wordt geladen, waardoor uw productiebundel geen ongebruikte vertalingen bevat.
+
+---
+
+## Vite-plugin: ingebouwde compiler en proxy
+
+De `intlayer()` Vite-plugin bundelt nu de **compiler** en de **locale-routeringsproxy** rechtstreeks, zodat de meeste projecten slechts één plugin nodig hebben in `vite.config.ts`:
+
+```ts fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [intlayer()],
+});
+```
+
+- **Compiler**: Wordt automatisch geactiveerd wanneer `compiler.enabled` is ingesteld op `true` en een `compiler.output`-pad is geconfigureerd. U hoeft `intlayerCompiler()` niet langer afzonderlijk te registreren.
+- **Proxy**: Wordt automatisch geactiveerd op basis van de nieuwe optie `routing.enableProxy` (standaard `true`). Het koppelt de middleware voor taaldetedering, omleiding en herschrijving in ontwikkeling, voorvertoning en productie-SSR. U hoeft `intlayerProxy()` niet langer afzonderlijk te registreren.
+
+### De optie `routing.enableProxy`
+
+Een nieuwe optie `routing.enableProxy` bepaalt of de locale-routeringsproxy wordt gekoppeld. De standaardwaarde is `true`. Schakel deze uit wanneer u de taalroutering zelf wilt afhandelen:
+
+```ts fileName="intlayer.config.ts"
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  routing: {
+    enableProxy: false, // Standaard: true
+  },
+};
+
+export default config;
+```
+
+De zelfstandige plugins `intlayerCompiler()` en `intlayerProxy()` blijven beschikbaar voor geavanceerde installaties. Het is veilig om ze samen met `intlayer()` te registreren — elke plugin dedupliceert zichzelf en wordt slechts één keer uitgevoerd.
+
+---
+
+## Compiler standaard uitgeschakeld
+
+Vanaf Intlayer v9 is de **compiler standaard uitgeschakeld** (`compiler.enabled` is nu standaard `false`). Om build-tijdextractie van uw `.content.ts`-bestanden in te schakelen, stelt u `compiler.enabled: true` in uw configuratie in:
+
+```ts fileName="intlayer.config.ts"
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  compiler: {
+    enabled: true, // Standaard: false — vereist om de compiler in te schakelen sinds v9
+    output: ({ fileName }) => `./${fileName}.content.ts`,
+  },
+};
+
+export default config;
+```
+
+Wanneer de compiler is uitgeschakeld, slaat Intlayer de build-tijdextractiestap over en vertrouwt op uw reeds gedeclareerde woordenboeken. Schakel deze alleen in wanneer u wilt dat de bundler-plugin (`@intlayer/swc`, `@intlayer/babel` of de `intlayer()` Vite-plugin) inhoud automatisch extraheert.
+
+---
+
+## React Native: importeren vanuit één pakket
+
+In een React Native- of Expo-app hoeft u niet langer zowel `react-intlayer` als `react-native-intlayer` te beheren. Het pakket `react-native-intlayer` **herexporteert nu de volledige `react-intlayer`-API** (hooks, hulpprogramma's en de subpaden `/format`, `/html` en `/markdown`), en de `IntlayerProvider` past de React Native polyfills automatisch toe.
+
+Importeer alles vanuit het enkele pakket `react-native-intlayer`:
+
+```tsx
+import {
+  IntlayerProvider,
+  useIntlayer,
+  useLocale,
+} from "react-native-intlayer";
+```
+
+```bash
+npm install intlayer react-native-intlayer
+```
+
+> Importeren vanuit `react-intlayer` blijft werken, maar `react-native-intlayer` is nu het aanbevolen enkelvoudige invoerpunt voor React Native — de provider bevat de polyfills die de webgerichte `react-intlayer`-provider niet heeft.
+
+---
+
+## CMS SDK: gebruik Intlayer als headless-contentdatabase
+
+Intlayer v9 levert een overzichtelijke, automatisch authenticerende SDK in `@intlayer/api` om programmatisch met de CMS te communiceren — haal projecten op, haal woordenboeken op en duw of update ze vanuit uw eigen server, scripts of CI. Authenticatie (OAuth2 `client_credentials`) wordt voor u beheerd en vernieuwd.
+
+De SDK is opgesplitst in **twee afzonderlijke imports** zodat uw bundel alleen de domeinen bevat die u daadwerkelijk gebruikt:
+
+1. `createIntlayerCMS` — een lichtgewicht **authenticator** die de referenties en het beheerde token bewaart (geen domein-client gebundeld).
+2. `dictionaryEndpoint`, `projectEndpoint`, … — per-domein **endpoint-binders**, elk geïmporteerd vanuit hun eigen subpad.
+
+```ts fileName="cms.ts"
+import { createIntlayerCMS } from "@intlayer/api";
+import { dictionaryEndpoint } from "@intlayer/api/dictionary";
+
+const cms = createIntlayerCMS();
+
+// Lezen
+const { data: dictionaries } = await dictionaryEndpoint(cms).getDictionaries();
+
+// Schrijven — gebruik de CMS als een database
+await dictionaryEndpoint(cms).pushDictionaries([myDictionary]);
+```
+
+> Beveiliging: de CMS-referenties verlenen schrijftoegang tot uw inhoud. Maak de authenticator altijd alleen aan **aan de serverzijde** — stuur `clientId`/`clientSecret` nooit naar de browser.
+
+---
+
+## Zelf hosten
+
+Intlayer v9 biedt eersteklas ondersteuning voor het uitvoeren van uw eigen Intlayer-instantie met één opdracht — geen Intlayer Cloud-account vereist.
+
+```sh
+curl -fsSL https://intlayer.org/install.sh | sh
+```
+
+Het installatieprogramma downloadt een `docker-compose.yml` en een `.env`, genereert automatisch de vereiste geheimen en voert `docker compose up -d` uit. Alles — het dashboard, de API, de database, objectopslag en transactionele e-mail — wordt lokaal in containers uitgevoerd.
+
+---
+
+## Migratienotities vanuit v8
+
+Als u upgradet vanuit v8, let dan op dat v9 geen breaking changes bevat. Maar dit zijn de belangrijkste wijzigingen:
+
+- **Compiler standaard uitgeschakeld**: `compiler.enabled` is nu standaard `false`. Als u afhankelijk bent van build-tijdextractie van uw `.content.ts`-bestanden, stelt u `compiler.enabled: true` in uw `intlayer.config.ts` in.
+- **Vite-plugin**: De compiler en locale-routeringsproxy zijn nu gebundeld in `intlayer()`. Als u eerder `intlayerCompiler()` of `intlayerProxy()` handmatig registreerde, kunt u ze verwijderen — ze worden automatisch gededupliceerd, dus ze bewaren is onschadelijk. Gebruik `routing.enableProxy: false` om de proxy uit te schakelen.
+- **Talen en dialecten**: Als u externe i18n-afhankelijkheden gebruikt, voeg dan de bijbehorende compat-adapterplugins toe in uw configuratie of bundler-installatie om imports automatisch te herschrijven.
+- **Aangepaste selectors**: Bij het aanroepen van `useIntlayer` is de tweede parameter nu gereserveerd voor een optieobject met `{ locale, item, variant }`. Als u eerder een taalstring direct doorgaf, kunt u dat nog steeds doen, maar het gebruik van het optieobject wordt aanbevolen voor geavanceerde selecties.
+- **React Native**: `react-native-intlayer` herexporteert nu de volledige `react-intlayer`-API. Importeer in een React Native-app alles vanuit `react-native-intlayer` en verwijder de directe `react-intlayer`-afhankelijkheid. Bestaande `react-intlayer`-imports blijven werken.
+
+---
+
+## Nuttige links
+
+- [Handleiding voor compat-adapterpakketten](https://github.com/aymericzip/intlayer/blob/main/docs/docs/nl/compat/index.md)
+- [Dynamische woordenboeken - Verzamelingen en varianten](https://github.com/aymericzip/intlayer/blob/main/docs/docs/nl/dynamic_dictionaries/index.md)
+- [Configuratiereferentie](https://github.com/aymericzip/intlayer/blob/main/docs/docs/nl/configuration.md)
+- [Handleiding voor React Native en Expo](https://github.com/aymericzip/intlayer/blob/main/docs/docs/nl/intlayer_with_react_native+expo.md)
+- [CMS SDK - Programmatische toegang met @intlayer/api](https://github.com/aymericzip/intlayer/blob/main/docs/docs/nl/intlayer_CMS.md)
+- [Handleiding voor zelf hosten](https://github.com/aymericzip/intlayer/blob/main/docs/docs/nl/self_hosting.md)

package/docs/pl/autoFill.md

@@ -35,6 +35,26 @@ author: aymericzip
 
 **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.