@intlayer/docs 9.0.0-canary.4 → 9.0.0-canary.5

package/docs/ko/releases/v7.md

@@ -25,6 +25,10 @@ author: aymericzip
 
 Intlayer v7에 오신 것을 환영합니다! 이번 주요 릴리스에서는 성능, 타입 안정성, 그리고 개발자 경험에서 큰 개선이 이루어졌습니다. 아래는 주요 내용과 마이그레이션 노트, 실용적인 예제들입니다.
 
+## 목차
+
+<TOC levels={[2]} maxDepth={1} />
+
 ## 주요 내용
 
 - 더 빠른 빌드를 위한 캐싱 전략
@@ -261,6 +265,126 @@ setLocale("en");
 
 ---
 
+## 자동 코드 포맷팅: formatCommand 구성
+
+v7은 편집기 구성에서 `formatCommand` 옵션을 도입하여, Intlayer에 의해 작성될 때 콘텐츠 파일을 자동으로 포맷할 수 있도록 합니다. 이를 통해 콘텐츠 선언 파일 전체에서 일관된 코드 스타일과 포맷팅을 보장합니다.
+
+설정되지 않은 경우, Intlayer는 포맷 명령을 자동으로 감지하려고 시도합니다. prettier, biome, eslint의 다음 명령들을 해석하려고 시도합니다.
+
+### 설정
+
+`formatCommand` 옵션은 `{{file}}`이 실제 파일 경로로 대체되는 문자열 템플릿을 허용합니다:
+
+```typescript fileName="intlayer.config.ts"
+export default {
+  content: {
+    formatCommand: 'bun x biome format "{{file}}" --write --log-level none',
+  },
+};
+```
+
+### 지원되는 포매터
+
+파일 경로를 인수로 받는 모든 코드 포매터를 사용할 수 있습니다:
+
+**Biome 사용:**
+
+```typescript
+formatCommand: 'bun x biome format "{{file}}" --write --log-level none';
+```
+
+**Prettier 사용:**
+
+```typescript
+formatCommand: 'npx prettier --write "{{file}}" --log-level silent';
+```
+
+**ESLint 사용:**
+
+```typescript
+formatCommand: 'npx eslint --fix "{{file}}" --quiet';
+```
+
+**Bun의 내장 포매터 사용:**
+
+```typescript
+formatCommand: 'bun format "{{file}}"';
+```
+
+### 이점
+
+- **일관된 형식 지정**: 모든 콘텐츠 파일이 프로젝트의 스타일 가이드라인에 따라 자동으로 형식이 지정됩니다
+- **개발자 경험**: Intlayer가 파일을 작성한 후 수동으로 형식을 지정할 필요가 없습니다
+- **팀 일관성**: 모든 팀 멤버가 동일한 형식을 콘텐츠 파일에 적용하도록 보장합니다
+- **CI/CD 통합**: 콘텐츠 파일이 자동화된 워크플로우에서 일관된 형식을 유지합니다
+
+### 작동 원리
+
+Intlayer가 content declaration 파일(`.content.ts`, `.content.js` 등)을 작성하거나 업데이트할 때, 지정된 format 명령을 파일에 대해 자동으로 실행합니다. `{{file}}` placeholder는 실제 파일 경로로 대체되며, 명령은 프로젝트의 base directory에서 실행됩니다.
+
+---
+
+## Dictionary Configuration: 더 나은 구성과 구조
+
+v7은 dictionary 관련 설정에 대한 더 나은 조직화와 개선된 컨텐츠 관리를 제공하는 새로운 전용 `dictionary` 설정 섹션을 도입합니다.
+
+### 새로운 dictionary 구성 구조
+
+`fill` 속성이 `content` 섹션에서 새로운 `dictionary` 섹션으로 이동되어 더 명확한 관심사의 분리를 제공합니다:
+
+**v6 configuration:**
+
+```typescript fileName="intlayer.config.ts"
+export default {
+  content: {
+    autoFill: "./{{fileName}}.content.json",
+    contentDir: ["src"],
+  },
+};
+```
+
+**v7 configuration:**
+
+```typescript fileName="intlayer.config.ts"
+export default {
+  content: {
+    contentDir: ["src"],
+  },
+  dictionary: {
+    fill: "./{{fileName}}.content.json",
+  },
+};
+```
+
+### 새로운 구조의 이점
+
+- **더 명확한 구성**: 사전 관련 설정이 이제 함께 그룹화되어 있습니다
+- **더 나은 관심사의 분리**: 콘텐츠 발견과 사전 작업이 명확하게 분리됩니다
+- **향상된 유지보수성**: 사전 관련 구성을 더 쉽게 이해하고 수정할 수 있습니다
+- **향후 확장성**: 사전 섹션은 추가 사전 관련 설정을 수용할 수 있습니다
+- **포괄적인 사전 관리**: 새로운 사전을 만들고 관리하기 위한 `title`, `live`, `priority`, `tags`, `version`, `description`과 같은 속성을 포함합니다
+
+### 구성 사용
+
+dictionary 구성은 두 가지 주요 목적을 수행합니다:
+
+1. **기본값**: 콘텐츠 선언 파일을 생성할 때 기본값 정의
+2. **Fallback 동작**: 특정 필드가 정의되지 않았을 때 fallback 값을 제공하여 dictionary 작동 동작을 전역적으로 정의 가능
+
+dictionary 섹션에는 dictionary 관리를 위한 포괄적인 속성이 포함됩니다:
+
+- **`fill`**: 콘텐츠 생성을 위한 자동 채우기 동작
+- **`title`**: 새 dictionary의 기본 제목
+- **`live`**: 실시간 업데이트를 위한 라이브 동기화 구성
+- **`priority`**: dictionary 해석 우선순위 설정
+- **`tags`**: 콘텐츠 조직화를 위한 기본 태그
+- **`version`**: dictionary 업데이트를 위한 버전 관리
+- **`description`**: 새 콘텐츠의 기본 설명
+
+콘텐츠 선언 파일 및 구성 값이 적용되는 방법에 대한 자세한 정보는 [Content File Documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/dictionary/content_file.md)을 참조하세요.
+
+---
+
 ## fill 명령어: 더 나은 콘텐츠 관리를 위한 동작 업데이트
 
 v7에서는 `fill` 명령어의 동작이 개선되어 더 예측 가능하고 유연한 콘텐츠 관리를 제공합니다:
@@ -408,6 +532,10 @@ const content = {
 - **`middleware.prefixDefault`**: `routing.mode`로 대체됨
 - **`middleware.noPrefix`**: `routing.mode`로 대체됨
 
+### 새로운 설정
+
+- **`editor.formatCommand`**: 콘텐츠 파일의 자동 코드 포맷팅을 위한 새로운 옵션
+
 ### 마이그레이션 매핑
 
 #### 구성 매핑

package/docs/ko/releases/v9.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-06-14
-updatedAt: 2026-06-14
+updatedAt: 2026-06-23
 title: 새로운 Intlayer v9 - 무엇이 달라졌나요?
 description: Intlayer v9의 새로운 기능을 알아보세요. 인기 있는 i18n 라이브러리를 위한 드롭인 호환성 패키지와 컬렉션(Collections), 베리언트(Variants), 동적 레코드(Dynamic Records) 지원을 소개합니다.
 keywords:
@@ -216,6 +216,42 @@ export default {
 
 ---
 
+## Vite Plugin: 번들된 컴파일러 & 프록시
+
+`intlayer()` Vite 플러그인은 이제 **컴파일러**와 **로케일 라우팅 프록시**를 직접 번들로 제공하므로, 대부분의 프로젝트는 `vite.config.ts`에서 단일 플러그인만 필요합니다:
+
+```ts fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [intlayer()],
+});
+```
+
+- **Compiler**: `compiler.enabled`가 설정되고 `compiler.output` 경로가 구성되면 자동으로 활성화됩니다. 더 이상 `intlayerCompiler()`를 별도로 등록할 필요가 없습니다.
+- **Proxy**: 새로운 `routing.enableProxy` 옵션(`기본값: true`)을 기반으로 자동으로 활성화됩니다. 개발, 미리보기 및 프로덕션 SSR에서 로케일 감지 / 리다이렉트 / 재작성 미들웨어를 연결합니다. 더 이상 `intlayerProxy()`를 별도로 등록할 필요가 없습니다.
+
+### `routing.enableProxy` 옵션
+
+새로운 `routing.enableProxy` 옵션은 locale-routing proxy가 연결되는지 여부를 제어합니다. 기본값은 `true`입니다. locale routing을 직접 처리하고 싶을 때 비활성화하세요:
+
+```ts fileName="intlayer.config.ts"
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  routing: {
+    enableProxy: false, // 기본값: true
+  },
+};
+
+export default config;
+```
+
+독립형 `intlayerCompiler()` 및 `intlayerProxy()` 플러그인은 고급 설정을 위해 계속 내보내집니다. 이들을 `intlayer()`와 함께 등록하는 것은 안전합니다 — 각 플러그인은 자동으로 중복을 제거하고 한 번만 실행됩니다.
+
+---
+
 ## v8에서의 마이그레이션 노트
 
 v8에서 업그레이드하는 경우, v9에는 하위 호환성을 깨뜨리는 변경 사항(breaking changes)이 포함되어 있지 않습니다. 하지만 다음과 같은 주요 변경 사항이 있습니다:

package/docs/ko/roadmap.md

@@ -29,6 +29,12 @@ Intlayer는 애플리케이션 전반에서 콘텐츠를 선언, 관리 및 업
 
 ---
 
+## 목차
+
+<TOC/>
+
+---
+
 ## 현재 기능
 
 ### 1. 콘텐츠 선언

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.

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).

package/docs/pl/benchmark/___solid.md

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

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

package/docs/pl/benchmark/___tanstack.md

@@ -0,0 +1,36 @@
+---
+createdAt: 2026-04-20
+updatedAt: 2026-04-21
+title: Najlepsze rozwiązanie i18n dla TanStack Start w 2026 - Raport benchmarku
+description: Porównaj biblioteki internacjonalizacji TanStack Start takie jak react-i18next, use-intl i Intlayer. Szczegółowy raport wydajności dotyczący rozmiaru bundle, wycieków i reaktywności.
+keywords:
+  - benchmark
+  - i18n
+  - intl
+  - tanstack
+  - wydajność
+  - intlayer
+slugs:
+  - doc
+  - benchmark
+  - tanstack
+author:
+  name: Aymeric PINEAU
+  github: aymericzip
+history:
+  - version: 8.7.5
+    date: 2026-01-06
+    changes: "Init benchmark"
+---
+
+# Raport benchmarku bibliotek i18n dla TanStack Start w 2026
+
+Ta strona jest raportem benchmarku dla rozwiązań i18n dla TanStack Start.
+
+## Interaktywny benchmark
+
+<I18nBenchmark framework="tanstack" 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-tanstack.md)