@intlayer/docs 9.4.1 → 9.4.3

package/blog/pl/is_next-intl_outdated.md

@@ -0,0 +1,363 @@
+---
+createdAt: 2026-09-02
+updatedAt: 2026-09-02
+title: Czy next-intl jest przestarzały w 2026 roku?
+description: next-intl stał się domyślnym wyborem dla Next.js App Router. Mimo to nadal obciąża bundle narzutem w runtime i wymaga ręcznego dzielenia na namespace'y.
+keywords:
+  - next-intl
+  - Intlayer
+  - Internacjonalizacja
+  - i18n
+  - Next.js
+  - Rozmiar bundle
+  - Blog
+  - JavaScript
+slugs:
+  - blog
+  - is-next-intl-outdated
+author: aymericzip
+---
+
+# Czy next-intl jest przestarzały w 2026 roku?
+
+Gdy Vercel wprowadził App Router i usunął wbudowane i18n z Pages Router, `next-intl` błyskawicznie wypełnił tę lukę. Jan Amann zapewnił dopracowaną dokumentację oraz szybkie wsparcie dla App Routera, co uczyniło bibliotekę standardem w społeczności.
+
+Dlaczego warto więc postawić pytanie o jej aktualną formę?
+
+**Architektura aplikacji webowych przeszła głęboką transformację w ciągu ostatnich trzech lat, podczas gdy fundamenty `next-intl` pozostały nienaruszone.**
+
+Podczas gdy Next.js rozwijał React Server Components (RSC), streaming oraz optymalizacje na poziomie kompilatora, `next-intl` wciąż traktuje internacjonalizację jako zadanie wykonywane w runtime: przekazuje obszerne obiekty JSON do providerów klienta, wykonuje parser ICU w przeglądarce i wymaga ręcznego podziału na namespace'y, aby powstrzymać rozrost bundle.
+
+<TOC/>
+
+## Kluczowe wnioski
+
+**Ustabilizowane tempo rozwoju:**
+
+W ciągu ostatnich 12 miesięcy `next-intl` zebrał ~187 commitów, skupionych w zasadzie wyłącznie na kompatybilności z Next.js oraz bieżących poprawkach.
+
+**Koszt w czasie wykonywania:**
+
+Zamontowanie `NextIntlClientProvider` z `useTranslations()` powiększa kod klienta o ~12.8 KB gzipped (51 KB minified) zanim pojawi się pierwsze słowo, czyli około trzykrotnie więcej niż `next-intlayer` (4.3 KB).
+
+**Wyciek 90% treści:**
+
+W typowych konfiguracjach **89.8% danych tłumaczeń przesyłanych do danej strony dotyczy zupełnie innych podstron**. Wejście na `/contact` powoduje pobranie treści z `/pricing` czy panelu administracyjnego.
+
+**Ręczny podział na namespace'y:**
+
+Uniknięcie nadmiarowego kodu wymaga żmudnego, ręcznego mapowania namespace'ów dla poszczególnych tras, co rodzi ryzyko braków w środowisku produkcyjnym.
+
+**Współpraca z Crowdin:**
+
+Jako oficjalny partner Crowdin, projekt nie ma wyraźnego powodu, by tworzyć bezpłatne narzędzie do lokalnego tłumaczenia AI bezpośrednio w CLI.
+
+## Utrzymanie vs. współczesne narzędzia
+
+Aktywność commitów w ostatnich dwunastu miesiącach:
+
+| Repozytorium          | Gwiazdki                                                                                                                                               | Wszystkie commity                                                                                                                                                   | Commity / rok                                                                                                                                                      | Ostatni commit                                                                                                                               |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `amannn/next-intl`    | [![stars](https://img.shields.io/github/stars/amannn/next-intl?style=for-the-badge&label=stars)](https://github.com/amannn/next-intl/stargazers)       | [![commits](https://img.shields.io/github/commit-activity/t/amannn/next-intl?style=for-the-badge&label=commits)](https://github.com/amannn/next-intl/commits)       | [![yearly](https://img.shields.io/github/commit-activity/y/amannn/next-intl?style=for-the-badge&label=%2Fyear)](https://github.com/amannn/next-intl/commits)       | [![last](https://img.shields.io/github/last-commit/amannn/next-intl?style=for-the-badge)](https://github.com/amannn/next-intl/commits)       |
+| `aymericzip/intlayer` | [![stars](https://img.shields.io/github/stars/aymericzip/intlayer?style=for-the-badge&label=stars)](https://github.com/aymericzip/intlayer/stargazers) | [![commits](https://img.shields.io/github/commit-activity/t/aymericzip/intlayer?style=for-the-badge&label=commits)](https://github.com/aymericzip/intlayer/commits) | [![yearly](https://img.shields.io/github/commit-activity/y/aymericzip/intlayer?style=for-the-badge&label=%2Fyear)](https://github.com/aymericzip/intlayer/commits) | [![last](https://img.shields.io/github/last-commit/aymericzip/intlayer?style=for-the-badge)](https://github.com/aymericzip/intlayer/commits) |
+
+Podsumowanie minionego roku:
+
+- `amannn/next-intl`: **187 commitów** (głównie aktualizacje zależności i drobne poprawki).
+- `aymericzip/intlayer`: **4 343 commity** (ciągłe prace nad kompilatorem, rozszerzeniami IDE, serwerami MCP i narzędziami tłumaczeniowymi).
+
+[![Star History Chart](https://api.star-history.com/chart?repos=amannn%2Fnext-intl%2Caymericzip%2Fintlayer&type=date&legend=top-left)](https://www.star-history.com/#amannn/next-intl&aymericzip/intlayer)
+
+Stabilna biblioteka bywa wystarczająca. Jednak standardy i18n uległy zmianie: kompilatory eliminują nieodwoływane tłumaczenia na etapie budowania, LLM-y wspierają translację w CI, a programiści korzystają z serwerów językowych (LSP) i asystentów AI. Biblioteka skupiona wyłącznie na czasie wykonywania nie czerpie z tych korzyści.
+
+## Wydajność w Next.js 16 App Router
+
+Wyniki testów standardowej aplikacji App Router z 10 trasami i 10 językami:
+
+<I18nBenchmark framework="nextjs" vertical/>
+
+<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;"
+/>
+
+> Testy przeprowadzone w realnych przeglądarkach z kompresją gzip. Kompletne dane w [raporcie benchmarku Next.js](https://intlayer.org/pl/doc/benchmark/nextjs).
+
+### Podstawowy narzut bibliotek
+
+Waga w przeglądarce przed dodaniem jakichkolwiek tłumaczeń:
+
+| Biblioteka             | Gzipped    | Zminifikowane |
+| ---------------------- | ---------- | ------------- |
+| `next-intl@4.9.1`      | 12.8 KB    | 51.0 KB       |
+| `next-intlayer@8.7.12` | **4.3 KB** | **13.3 KB**   |
+
+### Waga strony i wyciek danych
+
+| Konfiguracja           | Śr. JS / str. (gz) | Wyciek języków | Wyciek innych stron | Śr. komponent (gz) |
+| ---------------------- | ------------------ | -------------- | ------------------- | ------------------ |
+| Baza (bez i18n)        | 150.8 KB           | 0.0%           | 0.0%                | 0.7 KB             |
+| `next-intl` (statyka)  | 163.5 KB           | 4.2%           | **89.8%**           | 20.5 KB            |
+| `next-intl` (dynamika) | 163.4 KB           | 9.7%           | **89.9%**           | 20.5 KB            |
+| `next-intlayer`        | **152.1 KB**       | **0.0%**       | **0.0%**            | **7.2 KB**         |
+
+### Skąd bierze się wyciek między podstronami
+
+W powszechnych implementacjach `next-intl` główny layout pobiera wszystkie teksty za jednym razem:
+
+```tsx fileName="app/[locale]/layout.tsx"
+export default async function RootLayout({ children, params }) {
+  const messages = await getMessages();
+
+  return (
+    <html>
+      <body>
+        <NextIntlClientProvider messages={messages}>
+          {children}
+        </NextIntlClientProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+Ponieważ `messages` trafia do dostawcy klienta na samym szczycie drzewa, przeglądarka pobiera całą bazę słownikową przy każdym wejściu. Użytkownik wchodzący na `/login` pobiera również treści pomocy, cennika czy panelu użytkownika.
+
+Można temu zapobiegać, wydzielając namespace'y i ładując je warunkowo. Utrzymywanie tej konfiguracji ręcznie bywa jednak czasochłonne i ryzykowne.
+
+Intlayer rozwiązuje ten problem analizą statyczną: [kompilator Intlayer](https://intlayer.org/pl/doc/compiler) przygotowuje dla każdej trasy wyłącznie te teksty, które faktycznie się na niej znajdują, redukując wyciek do **0.0%**.
+
+## Dlaczego next-intl nie obsługuje tree-shakingu
+
+API biblioteki opiera się na dynamicznych kluczach tekstowych wywoływanych w runtime:
+
+<Tabs defaultTab="intlayer" group="techno">
+  <Tab label="next-intl" value="next-intl">
+
+```tsx fileName="UserProfile.tsx"
+"use client";
+
+import { useTranslations } from "next-intl";
+
+export function UserProfile() {
+  const t = useTranslations("UserProfile");
+
+  return <h2>{t("heading")}</h2>;
+}
+```
+
+  </Tab>
+  <Tab label="Intlayer" value="intlayer">
+
+```tsx fileName="UserProfile.tsx"
+"use client";
+
+import { useIntlayer } from "next-intlayer";
+
+export function UserProfile() {
+  const { heading } = useIntlayer("user-profile");
+
+  return <h2>{heading}</h2>;
+}
+```
+
+  </Tab>
+</Tabs>
+
+Turbopack oraz Webpack nie są w stanie określić, po które klucze z `UserProfile` sięgnie kod w przeglądarce. By zapobiec błędom brakujących tłumaczeń, **bundler musi wysłać cały namespace do klienta**. Destrukturyzowane właściwości w Intlayer pozwalają kompilatorowi precyzyjnie sprawdzić referencje i wyczyścić nieużywany tekst. Szczegóły znajdziesz w [optymalizacji bundle](https://intlayer.org/pl/doc/concept/bundle-optimization).
+
+## Doświadczenie programisty
+
+### Oddzielny JSON vs. ko-lokacja
+
+W `next-intl` teksty znajdują się w osobnych plikach JSON w oddalonym folderze `messages/`. Intlayer umieszcza definicje treści bezpośrednio obok komponentów:
+
+<Tabs defaultTab="intlayer" group="techno">
+  <Tab label="next-intl" value="next-intl">
+
+```json fileName="messages/en.json"
+{
+  "authModal": {
+    "title": "Sign in to your account",
+    "submitButton": "Continue"
+  }
+}
+```
+
+```json fileName="messages/pl.json"
+{
+  "authModal": {
+    "title": "Zaloguj się na swoje konto",
+    "submitButton": "Kontynuuj"
+  }
+}
+```
+
+```tsx fileName="AuthModal.tsx"
+import { useTranslations } from "next-intl";
+
+export const AuthModal = () => {
+  const t = useTranslations("authModal");
+  return (
+    <form>
+      <h2>{t("title")}</h2>
+      <button type="submit">{t("submitButton")}</button>
+    </form>
+  );
+};
+```
+
+  </Tab>
+  <Tab label="Intlayer" value="intlayer">
+
+```ts fileName="AuthModal.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+export default {
+  key: "auth-modal",
+  content: {
+    title: t({
+      en: "Sign in to your account",
+      pl: "Zaloguj się na swoje konto",
+    }),
+    submitButton: t({
+      en: "Continue",
+      pl: "Kontynuuj",
+    }),
+  },
+} satisfies Dictionary;
+```
+
+```tsx fileName="AuthModal.tsx"
+import { useIntlayer } from "next-intlayer";
+
+export const AuthModal = () => {
+  const { title, submitButton } = useIntlayer("auth-modal");
+  return (
+    <form>
+      <h2>{title}</h2>
+      <button type="submit">{submitButton}</button>
+    </form>
+  );
+};
+```
+
+  </Tab>
+</Tabs>
+
+Po przeniesieniu lub usunięciu `AuthModal.tsx` powiązane tłumaczenia są automatycznie synchronizowane.
+
+### Autouzupełnianie vs. ścisła weryfikacja typów
+
+Rozszerzenie `IntlMessages` w `next-intl` daje autouzupełnianie w edytorze na podstawie języka podstawowego:
+
+```ts fileName="global.d.ts"
+import en from "./messages/en.json";
+
+type Messages = typeof en;
+
+declare global {
+  interface IntlMessages extends Messages {}
+}
+```
+
+Weryfikowany jest jednak wyłącznie plik domyślny. Jeśli usuniesz wpis z `pl.json`, TypeScript nie zgłosi błędu, pipeline CI przejdzie pomyślnie, a użytkownicy napotkają puste miejsca w interfejsie.
+
+Intlayer tworzy typy dla wszystkich zadeklarowanych treści. Włączenie [`strictMode`](https://intlayer.org/pl/doc/concept/configuration) wymusza błąd budowania, jeśli w którymkolwiek języku zabraknie tłumaczenia.
+
+### Zestaw narzędzi i asystenci AI
+
+| Funkcjonalność                    | `next-intl` | Intlayer                                                                   |
+| --------------------------------- | ----------- | -------------------------------------------------------------------------- |
+| **Rozszerzenie VS Code**          | ❌ Brak     | ✅ [Oficjalne rozszerzenie](https://intlayer.org/pl/doc/vs-code-extension) |
+| **Language Server (LSP)**         | ❌ Brak     | ✅ [Zintegrowany LSP](https://intlayer.org/pl/doc/lsp)                     |
+| **Serwer MCP (dla agentów AI)**   | ❌ Brak     | ✅ [Wbudowany serwer MCP](https://intlayer.org/pl/doc/mcp-server)          |
+| **Umiejętności agentów (Skills)** | ❌ Brak     | ✅ [Gotowe skille](https://intlayer.org/pl/doc/agent_skills)               |
+| **Wizualny CMS in-context**       | ❌ Brak     | ✅ [Darmowy & Open Source](https://intlayer.org/pl/doc/concept/editor)     |
+
+Obecność serwera LSP i MCP pozwala asystentom AI lepiej rozumieć relacje między treściami i proponować dokładniejsze uzupełnienia.
+
+## Partnerstwo z Crowdin
+
+`next-intl` współpracuje z firmą Crowdin. Sponsoring sprzyja projektom open source, ale rzutuje na priorytety: biblioteka stworzona jako klient zewnętrznych systemów TMS raczej nie wdroży wbudowanego, darmowego narzędzia do lokalnego tłumaczenia AI.
+
+Intlayer udostępnia te mechanizmy bez dodatkowych opłat:
+
+**Lokalne auto-tłumaczenie AI (`intlayer fill`):**
+
+Wyszukuje i uzupełnia brakujące klucze, korzystając z Twoich prywatnych kluczy API OpenAI, Anthropic, Mistral lub Gemini.
+
+**Samodzielnie hostowany CMS wizualny:**
+
+Skorzystaj z [Intlayer CMS](https://intlayer.org/pl/doc/concept/cms), by dać zespołom nietechnicznym możliwość edycji treści z bezpośrednim zapisem w Git.
+
+**Licencja open source:**
+
+Wszystkie narzędzia są dostępne na warunkach licencji Apache 2.0.
+
+## Kiedy next-intl pozostaje odpowiednim wyborem?
+
+<AccordionGroup>
+<Accordion header="Zaawansowane konstrukcje ICU MessageFormat">
+
+Gdy aplikacja w dużym stopniu polega na specyficznych regułach liczby mnogiej i złożonym formatowaniu, implementacja ICU w `next-intl` jest w pełni sprawdzona.
+
+</Accordion>
+<Accordion header="Zorganizowane procesy oparte na Crowdin">
+
+W zespołach, których cały obieg tłumaczeń jest już powiązany z Crowdin, `next-intl` sprawdza się naturalnie.
+
+</Accordion>
+<Accordion header="Działające, stabilne serwisy">
+
+Jeśli projekt funkcjonuje zgodnie z oczekiwaniami, a rozmiar paczki nie wpływa negatywnie na wyniki, migracja nie jest pilna.
+
+</Accordion>
+</AccordionGroup>
+
+## Jak usprawnić istniejącą konfigurację next-intl?
+
+Intlayer oferuje gotowy pakiet kompatybilności, który wiernie odtwarza sygnatury funkcji i hooków `next-intl` (takich jak `useTranslations`, `getTranslations` oraz pomocniki routingu). Nie musisz przepisywać komponentów, aby zyskać optymalizacje na poziomie kompilatora.
+
+Instalacja wymaga tylko jednego polecenia:
+
+```bash packageManager="npm"
+npx intlayer init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer init --interactive
+```
+
+To interaktywne CLI:
+
+1. Instaluje pakiet kompatybilności `@intlayer/next-intl`.
+2. Konfiguruje aliasy w bundlerze, aby dotychczasowe importy (`next-intl`, `next-intl/server`) wskazywały bezpośrednio na Intlayer, co pozwala usunąć starą bibliotekę z `package.json`.
+3. Natychmiast aktywuje diagnostykę Language Server (LSP), usuwa wycieki tłumaczeń między stronami (pełny tree-shaking) i uruchamia lokalne procesy tłumaczeń AI bez konieczności przeprowadzania gruntownego refaktoringu.
+
+Szczegółowe wskazówki znajdziesz w naszych poradnikach:
+
+- **Kompatybilność od ręki:** Zachowaj wywołania `useTranslations` za pomocą [warstwy zgodności z next-intl](https://intlayer.org/pl/doc/compatibility/next-intl).
+- **Przeprowadzka słowników:** Przekształć pliki JSON w uporządkowane struktury według naszego [poradnika migracji z next-intl](https://intlayer.org/pl/doc/migration/next-intl).
+- **Wariant hybrydowy:** Używaj `next-intl` do wyświetlania interfejsu, [łącząc go z Intlayer](https://intlayer.org/pl/blog/intlayer-with-next-intl) do lokalnych tłumaczeń AI.
+
+Zweryfikuj wagę i wycieki swojej strony dzięki darmowemu [skanerowi SEO i18n](https://intlayer.org/i18n-seo-scanner):
+
+<ClickToOpenIframe src="https://intlayer.org/i18n-seo-scanner" width="100%" height="600px" style="border:none;"/>
+
+## Przydatne materiały
+
+- [Benchmark Next.js i18n: kompletne zestawienie](https://intlayer.org/pl/doc/benchmark/nextjs)
+- [next-i18next vs next-intl vs Intlayer](https://intlayer.org/pl/blog/next-i18next-vs-next-intl-vs-intlayer)
+- [Czy i18next jest przestarzały w 2026 roku?](https://intlayer.org/pl/blog/is-i18next-outdated)
+- [Dlaczego warto wybrać internacjonalizację opartą na kompilatorze](https://intlayer.org/pl/blog/compiler-vs-declarative-i18n)