@intlayer/docs 9.5.3 → 9.5.4

package/docs/en/benchmark/___solid.md

@@ -1,12 +0,0 @@
-- solid primitive is extreamly light and efficient, i recommand that solution for light project, but can quickly become lacking feature for professional solution including cooky management, proxy redirection, formatters etc.
-  Also miss lazy loading and scoping namespaces for page size optimization
-
-**(solid-i18next)** (`solid-i18next@17.0.2`):
-
-`solid-i18next` is probably the most popular option because it was among the first to serve JavaScript app i18n needs. It also has a wide set of community plugins for specific problems.
-
-Still, it shares the same major downsides as stacks built on `t('a.b.c')`: optimizations are possible but very time-consuming, and large projects risk bad practices (namespaces + dynamic loading + types).
-
-**(Intlayer)** (`svelte-intlayer@8.7.12`):
-
-I will not personally judge `svelte-intlayer` for objectivity’s sake, since it is my own solution.

package/docs/en/benchmark/___svelte.md

@@ -1,16 +0,0 @@
-**(Paraglide)** (`@inlang/paraglide-js@2.15.1`):
-
-`Paraglide` offers an innovative, well-thought-out approach.
-In the context of a vite+svelte app, the tree-shaking their company advertises work as expected, wich is great.
-But in the case of a react + tanstack/start, the tree-shaking did not work as expected, same for next.js. That's say I would be double chechking the usage of paraglide in a svelte and tanstack/start project.
-The workflow and DX are also more complex than other options.
-Personally I dislike having to regenerate JS files before every push, which creates constant merge conflict risk via PRs. The tool also seems more focused on Vite than on Next.js.
-Finally, in comparison with other solutions, Paraglide does not use a store (e.g. Svelte store) to retrieve the current locale to render the content. For each node parsed, it will request the locale from the localStorage / cookie etc. It leads to execution of unnecessary logic that impacts the component reactivity.
-
-- svelte-i18n
-
-that solutions answers all needs for i18n in a svelte project. But as it's the case for i18next or other main i18n solution it's a bit heavy (15kb gzip in comparison with 2.3kb for intlayer once the app bundled).
-
-**(Intlayer)** (`svelte-intlayer@8.7.12`):
-
-I will not personally judge `svelte-intlayer` for objectivity’s sake, since it is my own solution.

package/docs/en/benchmark/___tanstack.md

@@ -1,190 +0,0 @@
----
-createdAt: 2026-04-20
-updatedAt: 2026-04-21
-title: Best i18n solution for TanStack Start in 2026 - Benchmark Report
-description: Compare TanStack Start internationalization libraries like react-i18next, use-intl, and Intlayer. Detailed performance report on bundle size, leakage, and reactivity.
-keywords:
-  - benchmark
-  - i18n
-  - intl
-  - tanstack
-  - performance
-  - intlayer
-slugs:
-  - doc
-  - benchmark
-  - tanstack
-history:
-  - version: 8.7.5
-    date: 2026-01-06
-    changes: "Init benchmark"
-author:
-  name: Aymeric PINEAU
-  github: aymericzip
----
-
-# TanStack Start i18n Libraries - 2026 Benchmark Report
-
-Cette page est un rapport de benchmark pour les solutions i18n pour TanStack Start.
-
-## Table of Contents
-
-<Toc/>
-
-## Interactive Benchmark
-
-<I18nBenchmark framework="tanstack" vertical/>
-
-## Results reference:
-
-<ClickToOpenIframe
-  src="https://intlayer.org/markdown?url=https%3A%2F%2Fraw.githubusercontent.com%2Fintlayer-org%2Fbenchmark-i18n%2Fmain%2Freport%2Fscripts%2Fsummarize-tanstack.md"
-  width="100%"
-  height="600px"
-  style="border:none;"
-/>
-
-> [See complete benchmark data](https://intlayer.org/markdown?url=https%3A%2F%2Fraw.githubusercontent.com%2Fintlayer-org%2Fbenchmark-i18n%2Fmain%2Freport%2Fscripts%2Fsummarize-tanstack.md)
-
-## Introduction
-
-Les solutions d'internationalisation font partie des dependances les plus impactantes pour une application React. Sur TanStack Start, le risque principal est de charger du contenu inutile: des traductions d'autres pages et d'autres locales dans le bundle d'une seule route.
-
-Au fur et a mesure que votre application grandit, ce probleme peut vite faire exploser le JavaScript envoye au client et ralentir la navigation.
-
-En pratique, pour les implementations les moins optimisees, une page internationalisee peut devenir plusieurs fois plus lourde que la version sans i18n.
-
-L'autre impact est sur la DX: declaration des contenus, types, organisation par namespaces, chargement dynamique, et gestion de la reactivite au changement de locale.
-
-## Teste ton application
-
-Pour detecter rapidement les problemes de leakage i18n, j'ai mis en place un scanner gratuit disponible [ici](https://intlayer.org/i18n-seo-scanner).
-
-## Problematic
-
-Deux axes sont essentiels pour limiter l'impact d'une application multilingue:
-
-- Splitter le contenu par page / namespace pour eviter de charger des dictionnaires entiers inutilement
-- Charger dynamiquement la bonne locale uniquement quand necessaire
-
-Comprendre les limitations techniques de ces approches:
-
-**Dynamic loading**
-
-Sans chargement dynamique, la plupart des solutions incluent les messages en memoire des le premier rendu, ce qui cree un surcout important pour les applications avec beaucoup de routes et de locales.
-
-Avec un chargement dynamique, il faut accepter un compromis: moins de JS initial, mais parfois une requete additionnelle au changement de langue.
-
-**Split du contenu**
-
-Les syntaxes basees sur `const t = useTranslation()` + `t('a.b.c')` sont tres pratiques mais poussent souvent a conserver de gros objets JSON en runtime. Ce modele rend le tree-shaking difficile si la bibliotheque ne propose pas une vraie strategie de split par page.
-
-## Methodology
-
-Pour ce benchmark, nous avons compare les librairies suivantes:
-
-- `Base App` (No i18n library)
-- `react-intlayer` (v8.7.5-canary.0)
-- `react-i18next` (v17.0.2)
-- `use-intl` (v4.9.1)
-- `@lingui/core` (v5.3.0)
-- `@inlang/paraglide-js` (v2.15.1)
-- `tolgee` (v7.0.0)
-- `react-intl` (v10.1.1)
-- `wuchale` (v0.22.11)
-- `gt-react` (vlatest)
-- `lingo.dev` (v0.133.9)
-
-Le framework utilise est `TanStack Start` avec une application multilingue de **10 pages** et **10 langues**.
-
-Et nous avons comparé **4 stratégies de chargement** :
-
-| Stratégie              | Pas de Namespaces (Global)                        | Avec Namespaces (Scoped)                                                |
-| :--------------------- | :------------------------------------------------ | :---------------------------------------------------------------------- |
-| **Chargement Static**  | **Static** : Tout en mémoire au démarrage.        | **Scoped Static** : Segmenté par namespace, tout chargé au démarrage.   |
-| **Chargement Dynamic** | **Dynamic** : Chargement à la demande par locale. | **Scoped Dynamic** : Chargement granulaire par namespace et par locale. |
-
-## Synthèse des stratégies
-
-- **Static** : Simple, aucune latence réseau après le chargement initial. Inconvénient : bundle size élevé.
-- **Dynamic** : Réduit le poids initial (lazy-loading). Idéal pour un grand nombre de locales.
-- **Scoped Static** : Permet une organisation propre du code (séparation logique) sans surcoût de requêtes réseau complexes.
-- **Scoped Dynamic** : Approche optimale pour le _Code Splitting_ et la performance. Minimise la charge mémoire en ne chargeant que le strict nécessaire pour la vue courante et la locale active.
-
-## Details des Resultats
-
-### 1 - Les solutions a fuire
-
-Certaines solutions tel que `gt-react` ou `lingo.dev` sont clairement des solutions à éviter. Ces solutions intègrent un combo vendor lock-in + empoisonnement de votre codebase. Et le comble étant que malgré de nombreuses heures à tenter de les implémenter, je n'ai jamais réussi à les faire fonctionner correctement sur TanStack Start (comme sur Next.js pour `gt-next`).
-
-Liste de problèmes rencontrés :
-
-**(General Translation)** (`gt-react@latest`) :
-
-- Pour une application ~110kb, `gt-react` peut y ajouter plus de 440kb additionnel (ordre de grandeur observé sur l'implémentation Next.js du même benchmark).
-- `Quota Exceeded, please upgrade your plan`, dès le premier build avec la solution General Translation.
-- Translations are not rendered; I get the error `Error: <T> used on the client-side outside of <GTProvider>`, which seems to be a bug in the library.
-- While implementing **gt-tanstack-start-react**, I also came across an [issue](https://github.com/generaltranslation/gt/issues/1210#event-24510646961) with the library: `does not provide an export named 'printAST' - @formatjs/icu-messageformat-parser`, which was making the application break. After reporting this issue, the maintainer fixed it within 24 hours.
-- These libraries use an anti-pattern through the `initializeGT()` function, blocking the bundle from tree-shaking cleanly.
-
-**(Lingo.dev)** (`lingo.dev@0.133.9`) :
-
-- Quota AI dépassé (ou dépendance serveur bloquante), rendant le flux de build / prod risqué sans payer.
-- The compiler was missing almost 40% of the translated content. I had to rewrite all `.map` into flat component blocks to make it work.
-- Their CLI is buggy and used to reset the config file with no reason.
-- At build, it totally erased the generated JSONs when there was new content added. As a result, you could end up with only a few keys erasing hundreds of existing keys.
-- I met reactivity issues with the library on TanStack Start: on locale change I had to force rerendering of the provider to make it work.
-
-### 2 - Les solutions experimentales
-
-**(Wuchale)** (`wuchale@0.22.11`) :
-
-L'idée de `Wuchale` est intéressante, mais n'est pas encore au stade de solution viable. J'ai rencontré des problèmes de réactivité avec la librairie, et ai dû forcer le rerendering de la provider pour faire fonctionner l'application sur TanStack Start. La documentation est aussi relativement peu claire, complexifiant la prise en main.
-
-### 3 - Les solutions 'ok'
-
-**(Paraglide)** (`@inlang/paraglide-js@2.15.1`) :
-
-`Paraglide` est une solution offrant une approche innovante, et bien pensée. Pour autant, dans le cadre de mon benchmark, on se rend compte que le tree-shaking que vend leur entreprise ne fonctionne ni pour mon implémentation Next.js, ni pour TanStack Start. Le flow et la DX est également plus complexe que les autres solutions. Et je ne suis personnellement pas fan du fait de devoir régénérer des fichiers JS avant chaque push, créant un risque de conflits constant entre les développeurs via leur PR.
-
-**(Tolgee)** (`tolgee@7.0.0`) :
-
-`Tolgee` est une solution répondant aux différents problèmes évoqués plus tôt. Mais j'ai trouvé la prise en main de la solution plus complexe que les autres solutions proposant des approches similaires. La solution ne propose pas de typesafety. Ce qui rend aussi la détection des clés manquantes à la compilation bien plus complexe. J'ai dû ré-encapsuler les fonctions de Tolgee par les miennes pour y ajouter la détection de clés manquantes.
-
-Sur TanStack Start, j'ai aussi rencontré des problèmes de réactivité : au changement de locale j'ai dû forcer le rerendering du provider, et m'abonner aux événements de changement de locale pour que le chargement dans une autre langue se comporte correctement.
-
-**(use-intl)** (`use-intl@4.9.1`) :
-
-`use-intl` est la brique « intl » la plus en vogue dans l'écosystème React (même famille que `next-intl`), et aussi une des plus mise en avant par les agents AI, mais selon moi à tort dans un contexte performance-first. Le get-started est assez simple. Mais en pratique, le process d'optimisation pour limiter le leakage est assez complexe. De même, la cohabitation du dynamic loading + namespacing + TypeScript types ralentit énormément le développement.
-
-Sur TanStack Start, vous n'avez pas les pièges spécifiques à Next.js (`setRequestLocale`, static rendering), mais vous gardez le même coeur du problème : sans discipline stricte, le bundle embarque vite trop de messages et la maintenance des namespaces par route devient vite pénible.
-
-**(react-i18next)** (`react-i18next@17.0.2`) :
-
-`react-i18next` est probablement la solution la plus populaire par le fait que ce soit l'une des premières à avoir répondu aux besoins d'internationalisation d'applications JavaScript. Cette solution propose aussi tout un tas de plugins communautaires pour répondre à certaines problématiques.
-
-Pour autant, cette solution présente les mêmes grands points noirs que les stacks basées sur une fonction `t('a.b.c')` : optimisations possibles mais extrêmement chronophages, et risque élevé de mauvaises pratiques sur les gros projets (namespaces + chargement dynamique + types).
-
-De plus, les formats de messages divergent : `use-intl` s'appuie sur le format ICU MessageFormat, alors que `i18next` utilise son propre format - ce qui complique encore plus si vous mélangez outillage ou migrations.
-
-**(Lingui)** (`@lingui/core@5.3.0`) :
-
-`Lingui` est une solution pour laquelle j'ai entendu beaucoup de bien. Mais j'ai personnellement trouvé le flow basé sur l'exécution de commandes `lingui extract` / `lingui compile` plus complexe que les autres approches, sans vrai avantage significatif dans ce benchmark TanStack Start. J'ai aussi noté le manque d'harmonie entre les syntaxes qui porte les IA à confusion (e.g. `t()`, `t''`, `i18n.t()`, `<Trans>`).
-
-**(react-intl)** (`react-intl@10.1.1`) :
-
-`react-intl` est une implémentation performante, produite par l'équipe Format.js. En revanche, la DX reste verbeuse : `const intl = useIntl()` + `intl.formatMessage({ id: "xx.xx" })` introduit de la complexité, un surcoût d'exécution JavaScript, et connecte l'instance i18n globale à beaucoup de nœuds du graphe React.
-
-### 4 - Mes recommendations
-
-Ce benchmark TanStack Start ne contient pas d'équivalent direct à `next-translate` (plugin Next.js + `getStaticProps`). Pour les équipes qui veulent absolument une API `t()` avec un écosystème mature, `react-i18next` et `use-intl` restent des choix « raisonnables », mais attendez-vous à investir beaucoup de temps dans l'optimisation pour éviter le leakage.
-
-**(Intlayer)** (`react-intlayer@8.7.5-canary.0`) :
-
-Enfin, je ne jugerais pas personnellement `react-intlayer`, par souci d'objectivité, étant donné qu'il s'agit de ma propre solution.
-
-### Personal note
-
-Cette note est personnelle et n'a pas d'impact sur les résultats du benchmark. Cependant, dans le monde de l'i18n on voit un consensus clair qui est d'utiliser une syntaxe telle que `const t = useTranslation('xx')` + `<>{t('xx.xx')}</>` pour traduire leur contenu.
-
-Cependant, dans le cadre d'applications React, l'injection d'une fonction sous forme de `ReactNode` est selon moi un anti-pattern. De plus, cela introduit une complexité additionnelle, pouvant être évitée, et un overhead de JavaScript execution (bien qu'imperceptible).

package/docs/en/benchmark/___vue.md

@@ -1,7 +0,0 @@
-- vue-i18n is without contestation the most used i18n library for vue, it has a lot of features and a huge ecosystem. but under the hood the solution is quite heavy. even if vue-i18n integrate lazy loading for messages, it miss a scoping feature. In the case of a classic Vue SPA app there is no issue, but for a nuxt app, using @nuxt/i18n, it leads to including the messages from all pages into a single one. For a big nuxt app including more than 10 pages, it can become really problematic.
-
-- fluent-vue offer one inovation attempt thought the .ftl format. the message organization is great, easier to get started. but in practice, the lack of typesafty increase the risk of error and can quickly become time consuming to debug. Moreever, that solution load the messages using a vite plugin that force the loading of all the content in all languages into each page. Additionally this is an extreamly heavy solution (92kb gziped in comparison of 24kb gzipped for vue-i18n and 2.7kb gzipped for intlayer once the app bundled on a vue app)
-
-**(Intlayer)** (`vue-intlayer@8.7.12`):
-
-I will not personally judge `vue-intlayer` for objectivity’s sake, since it is my own solution.

package/docs/pl/benchmark/___NOTE.md

@@ -1,101 +0,0 @@
----
-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

@@ -1,198 +0,0 @@
----
-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).

package/docs/pl/benchmark/___solid.md

@@ -1,36 +0,0 @@
----
-createdAt: 2026-04-20
-updatedAt: 2026-04-21
-title: Najlepsze rozwiązanie i18n dla Solid w 2026 - Raport benchmarku
-description: Porównaj biblioteki internacjonalizacji Solid. Szczegółowy raport wydajności dotyczący rozmiaru bundle, wycieków i reaktywności.
-keywords:
-  - benchmark
-  - i18n
-  - intl
-  - solid
-  - wydajność
-  - intlayer
-slugs:
-  - doc
-  - benchmark
-  - solid
-author:
-  name: Aymeric PINEAU
-  github: aymericzip
-history:
-  - version: 8.7.5
-    date: 2026-01-06
-    changes: "Init benchmark"
----
-
-# Raport benchmarku bibliotek i18n dla Solid w 2026
-
-Ta strona jest raportem benchmarku dla rozwiązań i18n dla Solid.
-
-## Interaktywny benchmark
-
-<I18nBenchmark framework="solid" vertical/>
-
-## Referencja wyników
-
-> [Patrz kompletne dane benchmarku](https://intlayer.org/markdown?url=https%3A%2F%2Fraw.githubusercontent.com%2Fintlayer-org%2Fbenchmark-i18n%2Fmain%2Freport%2Fscripts%2Fsummarize-solid.md)

package/docs/pl/benchmark/___svelte.md

@@ -1,36 +0,0 @@
----
-createdAt: 2026-04-20
-updatedAt: 2026-04-21
-title: Najlepsze rozwiązanie i18n dla Svelte w 2026 - Raport benchmarku
-description: Porównaj biblioteki internacjonalizacji Svelte. Szczegółowy raport wydajności dotyczący rozmiaru bundle, wycieków i reaktywności.
-keywords:
-  - benchmark
-  - i18n
-  - intl
-  - svelte
-  - wydajność
-  - intlayer
-slugs:
-  - doc
-  - benchmark
-  - svelte
-author:
-  name: Aymeric PINEAU
-  github: aymericzip
-history:
-  - version: 8.7.5
-    date: 2026-01-06
-    changes: "Init benchmark"
----
-
-# Raport benchmarku bibliotek i18n dla Svelte w 2026
-
-Ta strona jest raportem benchmarku dla rozwiązań i18n dla Svelte.
-
-## Interaktywny benchmark
-
-<I18nBenchmark framework="svelte" vertical/>
-
-## Referencja wyników
-
-> [Patrz kompletne dane benchmarku](https://intlayer.org/markdown?url=https%3A%2F%2Fraw.githubusercontent.com%2Fintlayer-org%2Fbenchmark-i18n%2Fmain%2Freport%2Fscripts%2Fsummarize-svelte.md)