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

package/blog/ko/intlayer_with_vue-i18n.md

@@ -57,28 +57,46 @@ Intlayer는 훌륭한 독립형 i18n 솔루션을 제공하지만(자세한 내
 
 ## vue-i18n과 함께 Intlayer 설정 단계별 가이드
 
-### 1단계: 의존성 설치
+<Steps>
+
+<Step number={1} title="의존성 설치">
 
 선호하는 패키지 관리자를 사용하여 필요한 패키지를 설치하세요:
 
+```bash packageManager="npm"
+npx intlayer-cli init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer-cli init --interactive
+```
+
+> `--interactive` 플래그는 선택 사항입니다. AI 에이전트인 경우 `intlayer-cli init`를 사용하세요.
+
+> 이 명령은 환경을 감지하고 필요한 패키지를 설치합니다. 예를 들어:
+
 ```bash packageManager="npm"
 npm install intlayer @intlayer/sync-json-plugin --save-dev
-npx intlayer init
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer @intlayer/sync-json-plugin --save-dev
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer @intlayer/sync-json-plugin --dev
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer @intlayer/sync-json-plugin --dev
-bun x intlayer init
 ```
 
 **패키지 설명:**
@@ -86,7 +104,9 @@ bun x intlayer init
 - **intlayer**: 콘텐츠 선언 및 관리를 위한 핵심 라이브러리
   /// **@intlayer/sync-json-plugin**: Intlayer 콘텐츠 선언을 vue-i18n JSON 형식과 동기화하는 플러그인
 
-### 2단계: JSON을 래핑하기 위한 Intlayer 플러그인 구현
+</Step>
+
+<Step number={2} title="JSON을 래핑하기 위한 Intlayer 플러그인 구현">
 
 지원하는 로케일을 정의하기 위해 Intlayer 구성 파일을 만듭니다:
 
@@ -125,7 +145,9 @@ CLI를 사용하여 JSON을 번역하거나 CMS를 통해 변경이 이루어지
 
 ---
 
-### (선택 사항) 3단계: 컴포넌트별 JSON 번역 구현
+</Step>
+
+<Step number={3} title="컴포넌트별 JSON 번역 구현" isOptional={true}>
 
 기본적으로 Intlayer는 JSON 파일과 콘텐츠 선언 파일을 모두 로드, 병합 및 동기화합니다. 자세한 내용은 [콘텐츠 선언 문서](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/dictionary/content_file.md)를 참조하세요. 하지만 원한다면 Intlayer 플러그인을 사용하여 코드베이스 어디에서나 지역화된 JSON을 컴포넌트별로 관리할 수도 있습니다.
 
@@ -169,6 +191,10 @@ export default config;
 
 ---
 
+</Step>
+
+</Steps>
+
 ## Git 설정
 
 생성된 파일을 버전 관리에서 제외하세요:

package/blog/ko/next-i18next_vs_next-intl_vs_intlayer.md

@@ -204,24 +204,6 @@ Next.js는 국제화된 라우팅(예: 로케일 세그먼트)을 기본적으
 
 ---
 
-## 누락된 번역 처리
-
-**next-intl**
-
-- **런타임 폴백**에 의존합니다(예: 키 또는 기본 로케일 표시). 빌드는 실패하지 않습니다.
-
-**next-i18next**
-
-- **런타임 폴백**에 의존합니다(예: 키 또는 기본 로케일 표시). 빌드는 실패하지 않습니다.
-
-**intlayer**
-
-- 누락된 로케일이나 키에 대해 **빌드 타임 감지**와 **경고/오류**를 제공합니다.
-
-**중요한 이유:** 빌드 중에 누락을 잡으면 프로덕션에서 “미스터리 문자열”을 방지하고 엄격한 릴리스 게이트와 일치합니다.
-
----
-
 ## 라우팅, 미들웨어 및 URL 전략
 
 <Columns>
@@ -1175,6 +1157,127 @@ export default robots;
 
 ---
 
+### 로케일 라우팅을 위한 Middleware
+
+<Tabs defaultTab="next-intl" group='techno'>
+  <Tab label="next-i18next" value="next-i18next">
+
+로케일 감지 및 라우팅을 처리하기 위한 middleware를 추가합니다:
+
+```ts fileName="src/middleware.ts"
+import { NextResponse, type NextRequest } from "next/server";
+import { defaultLocale, locales } from "@/i18n.config";
+
+const PUBLIC_FILE = /\.[^/]+$/; // 확장자가 있는 파일 제외
+
+export function middleware(request: NextRequest) {
+  const { pathname } = request.nextUrl;
+
+  if (
+    pathname.startsWith("/_next") ||
+    pathname.startsWith("/api") ||
+    pathname.startsWith("/static") ||
+    PUBLIC_FILE.test(pathname)
+  ) {
+    return;
+  }
+
+  const hasLocale = locales.some(
+    (l) => pathname === "/" + l || pathname.startsWith("/" + l + "/")
+  );
+  if (!hasLocale) {
+    const locale = defaultLocale;
+    const url = request.nextUrl.clone();
+    url.pathname = "/" + locale + (pathname === "/" ? "" : pathname);
+    return NextResponse.redirect(url);
+  }
+}
+
+export const config = {
+  matcher: [
+    // 이들로 시작하는 경로와 확장자가 있는 파일을 제외한 모든 경로와 일치
+    "/((?!api|_next|static|.*\\..*).*)",
+  ],
+};
+```
+
+  </Tab>
+  <Tab label="next-intl" value="next-intl">
+
+로케일 감지 및 라우팅을 처리하기 위한 middleware를 추가합니다:
+
+```ts fileName="src/middleware.ts"
+import createMiddleware from "next-intl/middleware";
+import { locales, defaultLocale } from "@/i18n";
+
+export default createMiddleware({
+  locales: [...locales],
+  defaultLocale,
+  localeDetection: true,
+});
+
+export const config = {
+  // API, Next 내부 및 정적 자산 건너뛰기
+  matcher: ["/((?!api|_next|.*\\..*).*)"],
+};
+```
+
+  </Tab>
+  <Tab label="intlayer" value="intlayer">
+
+Intlayer는 `next-intlayer` package 설정을 통한 기본 제공 middleware 처리를 제공합니다.
+
+```ts fileName="src/middleware.ts"
+import { intlayerProxy } from "next-intlayer/proxy";
+
+export const middleware = intlayerProxy();
+
+// app 디렉토리의 파일에만 이 middleware를 적용합니다
+export const config = {
+  matcher: "/((?!api|_next|static|.*\\..*).*)",
+};
+```
+
+middleware의 설정은 `intlayer.config.ts` 파일에 중앙화되어 있습니다.
+
+  </Tab>
+</Tabs>
+
+### 설정 체크리스트 및 모범 사례
+
+<Tabs defaultTab="next-intl" group='techno'>
+  <Tab label="next-i18next" value="next-i18next">
+
+- `src/app/[locale]/layout.tsx`의 루트 `<html>`에서 `lang`과 `dir`이 설정되어 있는지 확인하세요.
+- `src/locales/<locale>/` 아래에서 번역을 네임스페이스로 분할합니다 (예: `common.json`, `about.json`).
+- 클라이언트 컴포넌트에서 `useTranslation('<ns>')`를 사용하여 필요한 네임스페이스만 로드하고 `I18nProvider`를 동일한 네임스페이스로 범위를 제한합니다.
+- 가능한 경우 페이지를 정적으로 유지합니다: 페이지에서 `export const dynamic = 'force-static'`을 내보내고 `dynamicParams = false`를 설정하고 `generateStaticParams`를 구현합니다.
+- 이미 계산된 문자열이나 `t` 함수 및 `locale`을 전달하여 클라이언트 경계 아래에 동기 서버 컴포넌트를 사용합니다.
+- SEO의 경우, 메타데이터에서 `alternates.languages`를 설정하고 `sitemap.ts`에서 지역화된 URL을 나열하고 `robots.ts`에서 중복된 지역화된 경로를 비활성화합니다.
+- 로케일 인식 포매터 (예: `Intl.NumberFormat(locale)`)를 선호하고 React < 19를 사용하는 경우 클라이언트에서 메모이제이션합니다.
+
+  </Tab>
+  <Tab label="next-intl" value="next-intl">
+
+- **html `lang`과 `dir` 설정**: `src/app/[locale]/layout.tsx`에서 `getLocaleDirection(locale)`을 통해 `dir`을 계산하고 `<html lang={locale} dir={dir}>`을 설정합니다.
+- **네임스페이스별로 메시지 분할**: 로케일 및 네임스페이스별로 JSON을 구성합니다 (예: `common.json`, `about.json`).
+- **클라이언트 페이로드 최소화**: 페이지에서 필요한 네임스페이스만 `NextIntlClientProvider`로 전송합니다 (예: `pick(messages, ['common', 'about'])`).
+- **정적 페이지 선호**: `export const dynamic = 'force-static'`을 내보내고 모든 `locales`에 대한 정적 매개변수를 생성합니다.
+- **동기 서버 컴포넌트**: 비동기 호출이나 직렬화할 수 없는 함수 대신 사전 계산된 문자열 (번역된 레이블, 형식이 지정된 숫자)을 전달하여 서버 컴포넌트를 동기적으로 유지합니다.
+
+  </Tab>
+  <Tab label="intlayer" value="intlayer">
+
+- **모듈식 콘텐츠**: `.content.{ts|js|json}` 파일을 사용하여 콘텐츠 딕셔너리를 컴포넌트와 함께 배치합니다.
+- **타입 안전성**: TypeScript 통합을 활용하여 컴파일 타임 콘텐츠 검증을 수행합니다.
+- **빌드 타임 최적화**: Intlayer의 빌드 도구를 사용하여 자동 트리 셰이킹 및 번들 최적화를 수행합니다.
+- **통합 도구**: 기본 제공 라우팅, SEO 헬퍼 및 비주얼 에디터 지원을 활용합니다.
+
+  </Tab>
+</Tabs>
+
+---
+
 ## 그리고 승자는…
 
 간단하지 않습니다. 각 옵션마다 장단점이 있습니다. 제가 보는 관점은 다음과 같습니다:

package/blog/ko/rag_powered_documentation_assistant.md

@@ -57,43 +57,6 @@ RAG가 인기 있는 접근법이 된 데는 이유가 있습니다. 대형 언
 
 따라서 RAG는 단순한 지원 도구가 아닙니다. 그것은 또한 **제품 발견 엔진**입니다.
 
-## RAG 파이프라인 작동 방식
-
-![RAG Pipeline](https://github.com/aymericzip/intlayer/blob/main/docs/assets/rag_flow.svg)
-
-전체적인 개요는 다음과 같습니다:
-
-1.  **문서 청킹(Chunking)** 큰 마크다운 파일을 여러 청크로 분할합니다. 청킹은 문서의 관련된 부분만 컨텍스트로 제공할 수 있게 합니다.
-2.  **임베딩 생성(Generating embeddings)** 각 청크는 OpenAI의 임베딩 API(text-embedding-3-large) 또는 벡터 데이터베이스(Chroma, Qdrant, Pinecone)를 사용해 벡터로 변환됩니다.
-3.  **인덱싱 및 저장** 임베딩은 간단한 JSON 파일에 저장됩니다(데모용). 하지만 실제 운영 환경에서는 벡터 DB를 사용할 가능성이 높습니다.
-4.  **검색 (RAG의 R)** 사용자 쿼리를 임베딩하고, 코사인 유사도를 계산하여 가장 일치하는 청크들을 검색합니다.
-5.  **증강 및 생성 (RAG의 AG)** 해당 청크들을 ChatGPT 프롬프트에 주입하여, 모델이 실제 문서 컨텍스트를 기반으로 답변하도록 합니다.
-6.  **피드백을 위한 쿼리 기록** 모든 사용자 쿼리를 저장합니다. 이는 문제점 파악, 누락된 문서, 새로운 기회를 이해하는 데 매우 중요합니다.
-
-## 1단계: 문서 읽기
-
-첫 번째 단계는 간단했습니다: docs/ 폴더 내 모든 .md 파일을 스캔할 방법이 필요했습니다. Node.js와 glob을 사용하여 각 마크다운 파일의 내용을 메모리로 가져왔습니다.
-
-이것은 파이프라인을 유연하게 유지합니다: Markdown 대신 데이터베이스, CMS, 또는 API에서 문서를 가져올 수도 있습니다.
-
-## 2단계: 문서 청킹(Chunking)
-
-왜 청킹을 할까요? 언어 모델에는 **컨텍스트 제한**이 있기 때문입니다. 전체 문서 책을 한 번에 입력하는 것은 불가능합니다.
-
-그래서 텍스트를 관리 가능한 청크(예: 각 500 토큰)로 나누고, 겹치는 부분(예: 100 토큰)을 둡니다. 겹치는 부분은 청크 경계에서 의미가 끊기지 않도록 연속성을 보장합니다.
-
-**예시:**
-
-- 청크 1 → “…많은 이들이 잊어버린 오래된 도서관. 그 높이 솟은 선반들은 책들로 가득 차 있었다…”
-- 청크 2 → “…선반들은 상상할 수 있는 모든 장르의 책들로 가득 차 있었고, 각각이 이야기를 속삭이고 있었다…”
-
-이 겹침은 두 청크가 공유된 컨텍스트를 포함하도록 하여, 검색 시 일관성을 유지하게 합니다.
-
-이 절충안(청크 크기 대 중첩)은 RAG 효율성에 매우 중요합니다:
-
-- 너무 작으면 → 노이즈가 발생합니다.
-- 너무 크면 → 컨텍스트 크기가 너무 커집니다.
-
 ## 3단계: 임베딩 생성
 
 문서가 청크로 나뉘면, 각 청크를 나타내는 고차원 벡터인 **임베딩**을 생성합니다.
@@ -112,163 +75,6 @@ RAG가 인기 있는 접근법이 된 데는 이유가 있습니다. 대형 언
 
 각 벡터는 텍스트의 수학적 지문으로, 유사도 검색을 가능하게 합니다.
 
-## 4단계: 임베딩 인덱싱 및 저장
-
-임베딩을 여러 번 다시 생성하지 않도록, 저는 이를 embeddings.json에 저장했습니다.
-
-프로덕션 환경에서는 다음과 같은 벡터 데이터베이스를 사용하는 것이 좋습니다:
-
-- Chroma
-- Qdrant
-- Pinecone
-- FAISS, Weaviate, Milvus 등
-
-벡터 DB는 인덱싱, 확장성, 빠른 검색을 처리합니다. 하지만 제 프로토타입에서는 로컬 JSON으로도 충분했습니다.
-
-## 5단계: 코사인 유사도를 이용한 검색
-
-사용자가 질문을 하면:
-
-1. 쿼리에 대한 임베딩을 생성합니다.
-2. 모든 문서 임베딩과 **코사인 유사도**를 사용해 비교합니다.
-3. 가장 유사한 상위 N개의 청크만 유지합니다.
-
-코사인 유사도는 두 벡터 사이의 각도를 측정합니다. 완벽한 일치는 **1.0** 점수를 받습니다.
-
-이렇게 시스템은 쿼리와 가장 가까운 문서 구간을 찾습니다.
-
-## 6단계: 증강 + 생성
-
-이제 마법이 시작됩니다. 상위 청크들을 가져와 ChatGPT의 **시스템 프롬프트**에 주입합니다.
-
-그것은 모델이 마치 해당 청크들이 대화의 일부인 것처럼 답변한다는 의미입니다.
-
-결과: 정확하고, **문서 기반의 응답**.
-
-## 7단계: 사용자 쿼리 기록
-
-이것이 숨겨진 슈퍼파워입니다.
-
-모든 질문이 저장됩니다. 시간이 지나면서 다음과 같은 데이터셋을 구축할 수 있습니다:
-
-- 가장 빈번한 질문들 (FAQ에 매우 유용)
-- 답변되지 않은 질문들 (문서가 없거나 불명확한 경우)
-- 질문으로 위장된 기능 요청 (“X와 통합되나요?”)
-- 예상치 못한 새로운 사용 사례
-
-이로써 당신의 RAG 어시스턴트는 **지속적인 사용자 조사 도구**가 됩니다.
-
-## 비용은 얼마나 들까?
-
-RAG에 대한 흔한 반대 의견 중 하나는 비용입니다. 실제로는 놀라울 정도로 저렴합니다:
-
-- 약 200개의 문서에 대한 임베딩 생성은 약 **5분**이 걸리며 비용은 **1~2 유로**입니다.
-- 문서 검색 기능은 100% 무료입니다.
-- 쿼리의 경우, “thinking” 모드 없이 gpt-4o-latest를 사용합니다. Intlayer에서는 한 달에 약 **300건의 채팅 쿼리**가 발생하며, OpenAI API 요금은 거의 **$10**를 넘지 않습니다.
-
-여기에 호스팅 비용을 포함할 수 있습니다.
-
-## 구현 세부사항
-
-스택:
-
-- 모노레포: pnpm 워크스페이스
-- 문서 패키지: Node.js / TypeScript / OpenAI API
-- 프론트엔드: Next.js / React / Tailwind CSS
-- 백엔드: Node.js API 라우트 / OpenAI API
-
-`@smart-doc/docs` 패키지는 문서 처리를 담당하는 TypeScript 패키지입니다. 마크다운 파일이 추가되거나 수정되면, 이 패키지는 각 언어별 문서 목록을 재구성하고 임베딩을 생성하여 `embeddings.json` 파일에 저장하는 `build` 스크립트를 포함합니다.
-
-프론트엔드에는 다음 기능을 제공하는 Next.js 애플리케이션을 사용합니다:
-
-- 마크다운을 HTML로 렌더링
-- 관련 문서를 찾기 위한 검색 바
-- 문서에 대한 질문을 할 수 있는 챗봇 인터페이스
-
-문서 검색을 수행하기 위해, Next.js 애플리케이션은 쿼리에 맞는 문서 청크를 검색하는 `@smart-doc/docs` 패키지의 함수를 호출하는 API 라우트를 포함합니다. 이 청크들을 사용하여 사용자의 검색과 관련된 문서 페이지 목록을 반환할 수 있습니다.
-
-챗봇 기능의 경우, 동일한 검색 과정을 따르지만 추가로 검색된 문서 청크를 ChatGPT에 보내는 프롬프트에 주입합니다.
-
-다음은 ChatGPT에 보내는 프롬프트 예시입니다:
-
-시스템 프롬프트:
-
-```txt
-당신은 Intlayer 문서에 관한 질문에 답변할 수 있는 유용한 도우미입니다.
-
-관련 청크:
-
------
-docName: "getting-started"
-docChunk: "1/3"
-docUrl: "https://example.com/docs/ko/getting-started"
----
-
-# 시작하는 방법
-
-...
-
------
-docName: "another-doc"
-docChunk: "1/5"
-docUrl: "https://example.com/docs/ko/another-doc"
----
-
-# 다른 문서
-
-...
-```
-
-사용자 질의 :
-
-```txt
-시작하는 방법은?
-```
-
-우리는 API 경로에서 응답을 스트리밍하기 위해 SSE를 사용합니다.
-
-앞서 언급했듯이, 우리는 "생각하는" 모드 없이 gpt-4-turbo를 사용합니다. 응답은 관련성이 높고 지연 시간이 낮습니다.
-gpt-5도 실험해 보았지만, 지연 시간이 너무 길었고(때로는 응답에 최대 15초까지 걸림) 앞으로 다시 검토할 예정입니다.
-
-👉 [여기에서 데모를 시도해 보세요](https://intlayer.org/doc/why) 👉 [GitHub에서 코드 템플릿 확인하기](https://github.com/aymericzip/smart_doc_RAG)
-
-## 더 나아가기
-
-이 프로젝트는 최소한의 구현입니다. 하지만 여러 가지 방법으로 확장할 수 있습니다:
-
-- MCP 서버 → 문서 검색 기능을 MCP 서버로 확장하여 문서를 모든 AI 어시스턴트에 연결
-- 벡터 DB → 수백만 개의 문서 청크로 확장
-- LangChain / LlamaIndex → RAG 파이프라인을 위한 기성 프레임워크
-- 분석 대시보드 → 사용자 쿼리와 문제점을 시각화
-- 다중 소스 검색 → 문서뿐만 아니라 데이터베이스 항목, 블로그 게시물, 티켓 등도 검색
-- 향상된 프롬프트 → 재순위화, 필터링, 하이브리드 검색(키워드 + 의미 기반)
-
-## 우리가 직면한 한계
-
-- 청크 분할과 중첩은 경험적입니다. 적절한 균형(청크 크기, 중첩 비율, 검색된 청크 수)은 반복과 테스트가 필요합니다.
-- 문서가 변경될 때 임베딩이 자동으로 재생성되지 않습니다. 우리 시스템은 저장된 청크 수와 다를 때만 파일의 임베딩을 재설정합니다.
-- 이 프로토타입에서는 임베딩이 JSON에 저장됩니다. 이는 데모에는 적합하지만 Git을 오염시킵니다. 실제 운영 환경에서는 데이터베이스나 전용 벡터 스토어가 더 적합합니다.
-
-## 문서를 넘어 중요한 이유
-
-흥미로운 부분은 단순한 챗봇이 아닙니다. 바로 **피드백 루프**입니다.
-
-RAG를 사용하면 단순히 답변하는 것에 그치지 않습니다:
-
-- 사용자가 무엇에 혼란스러워하는지 알게 됩니다.
-- 사용자가 기대하는 기능을 발견합니다.
-- 실제 쿼리를 기반으로 제품 전략을 조정합니다.
-
-**예시:**
-
-새로운 기능을 출시하고 즉시 다음과 같은 상황을 상상해 보세요:
-
-- 질문의 50%가 동일한 불명확한 설정 단계에 관한 것
-- 사용자가 아직 지원하지 않는 통합 기능을 반복적으로 요청
-- 사람들이 새로운 사용 사례를 드러내는 용어를 검색
-
-이것이 바로 사용자로부터 직접 얻는 **제품 인텔리전스**입니다.
-
 ## 결론
 
 RAG는 LLM을 실용적으로 만드는 가장 간단하면서도 강력한 방법 중 하나입니다. **검색(retrieval) + 생성(generation)**을 결합함으로써 정적인 문서를 **스마트 어시스턴트**로 전환할 수 있으며, 동시에 지속적인 제품 인사이트 흐름을 얻을 수 있습니다.

package/blog/ko/react-i18next_vs_react-intl_vs_intlayer.md

@@ -146,6 +146,12 @@ author: aymericzip
 
 ---
 
+## GitHub STARs
+
+GitHub star는 프로젝트의 인기도, 커뮤니티 신뢰도, 장기적 관련성의 강력한 지표입니다. 기술적 품질의 직접적인 척도는 아니지만, 얼마나 많은 개발자가 프로젝트를 유용하다고 생각하는지, 진행 상황을 팔로우하는지, 그리고 이를 도입할 가능성이 있는지를 반영합니다. 프로젝트의 가치를 추정할 때, star는 대안들 간의 견인력을 비교하고 생태계 성장에 대한 통찰력을 제공하는 데 도움이 됩니다.
+
+[![Star History Chart](https://api.star-history.com/chart?repos=formatjs/formatjs%2Ci18next/react-i18next%2Caymericzip/intlayer&type=date&legend=top-left)](https://www.star-history.com/#formatjs/formatjs&i18next/react-i18next&aymericzip/intlayer)
+
 ## 결론
 
 세 가지 라이브러리 모두 React를 효과적으로 현지화합니다. 차별점은 **안전하고 확장 가능한** 환경을 구축하기 위해 얼마나 많은 **인프라**를 만들어야 하는가에 있습니다:

package/blog/ko/vue-i18n_vs_intlayer.md

@@ -259,6 +259,14 @@ const { greeting } = useIntlayer("component-example");
 
 ---
 
+## GitHub STARs
+
+GitHub stars는 프로젝트의 인기도, 커뮤니티 신뢰도, 장기적 관련성의 강력한 지표입니다. 기술적 품질을 직접 측정하는 것은 아니지만, 얼마나 많은 개발자들이 프로젝트를 유용하게 생각하고, 진행 상황을 따르고 있으며, 채택할 가능성이 있는지를 반영합니다. 프로젝트의 가치를 추정하기 위해 stars는 대안들 간의 견인력을 비교하고 생태계 성장에 대한 통찰력을 제공합니다.
+
+[![Star History Chart](https://api.star-history.com/svg?repos=intlify/vue-i18n&repos=aymericzip/intlayer&type=Date)](https://www.star-history.com/#intlify/vue-i18n&aymericzip/intlayer)
+
+---
+
 ## 결론
 
 **vue-i18n**과 **Intlayer** 모두 Vue 앱을 잘 현지화합니다. 차이점은 견고하고 확장 가능한 설정을 위해 **얼마나 많이 직접 구축해야 하는가**에 있습니다:

package/blog/ko/what_is_internationalization.md

@@ -74,10 +74,6 @@ i18n의 또 다른 중요한 이점은 사용자 경험의 향상입니다. 사
 
 ## 일반적인 i18n 도전 과제
 
-![i18n pain illustration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/assets/pain_i18n.webp)
-
-## 일반적인 i18n 도전 과제
-
 - **유지보수 가능성**  
   각 웹사이트 업데이트는 모든 언어에서 반영되어야 하므로 효율적인 작업 흐름과 조정이 필요하여 모든 버전 간의 일관성을 보장해야 합니다.
 

package/blog/pl/___per-component_vs_centralized_i18n.md

@@ -0,0 +1,100 @@
+---
+createdAt: 2025-09-10
+updatedAt: 2025-09-10
+title: "Per-Component vs. Centralized i18n: Nowe podejście z Intlayer"
+description: Dogłębne porównanie strategii internacjonalizacji w React, porównanie podejść scentralizowanych, per-key i per-component, oraz wprowadzenie Intlayer.
+keywords:
+  - i18n
+  - React
+  - Internationalization
+  - Intlayer
+  - Optimization
+  - Bundle Size
+slugs:
+  - blog
+  - per-component-vs-centralized-i18n
+author:
+  name: Aymeric PINEAU
+  github: aymericzip
+---
+
+# Per-Component vs. Centralized i18n
+
+Jestem twórcą Intlayer, rozwiązania i18n, które przyjmuje **podejście per-component**.
+
+Podejście per-component nie jest dokładnie nowe.
+Po stronie Vue, `vue-i18n` ma podejście ['Single File Components'](https://vue-i18n.intlify.dev/guide/advanced/sfc.html). Istnieje również w Nuxt z tłumaczeniami per-component [tutaj](https://i18n.nuxtjs.org/docs/guide/per-component-translations).
+
+Nawet w aplikacji Flutter możemy często znaleźć ten wzorzec:
+
+```bash
+lib/
+├── features/
+│   ├── login/
+│   │   ├── login_screen.dart
+│   │   └── login_screen.i18n.dart  <- Tłumaczenia żyją tutaj
+
+```
+
+```dart
+import 'package:i18n_extension/i18n_extension.dart';
+
+extension Localization on String {
+  static var _t = Translations("en_us") +
+      {
+        "en_us": "Hello",
+        "pt_br": "Olá",
+        "es": "Hola",
+      };
+
+  String get i18n => localize(this, _t);
+}
+
+```
+
+Niemniej jednak, w świecie React, głównie widzimy różne podejścia, które pogrupuję w trzy kategorie:
+
+1. **Podejście scentralizowane** (i18next, next-intl, react-intl, lingui)
+2. **Podejście per-component** (Intlayer)
+3. **Podejście per-key** (inlang)
+
+W tym blogu nie będę skupiać się na rozwiązaniach bazujących na kompilatorze, które już omówiłem tutaj: [Compiler vs Declarative i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/compiler_vs_declarative_i18n.md).
+Zauważ, że compiler-based i18n (np. Lingui) po prostu automatyzuje ekstrakcję i ładowanie zawartości. Za kulisami, często dzielą te same ograniczenia co podejście scentralizowane.
+
+Co zatem są różnice?
+
+- **Podejście scentralizowane** (bez namespaces) rozważa pojedyncze źródło do pobierania zawartości. Domyślnie ładujesz zawartość wszystkich stron przy załadowaniu aplikacji.
+- **Podejścia per-component i per-key** drobniutko dzielą pobieranie zawartości.
+
+> Zauważ, że im bardziej dzielisz jak pobierasz zawartość, tym bardziej ryzykujesz wstawiać dodatkowy stan i logikę do komponentów.
+> Na przykład, strona może łatwo zawierać 500 węzłów tekstu (`<p>`, `<span>`). Podejście per-key efektywnie wstawi 500 nowych instancji komponentu aby obsłużyć tłumaczenie, każde potencjalnie używając własnego `useState`, `useEffect`, lub `useContext`.
+
+Tutaj jest wizualizacja kompromisu:
+
+```bash
+Count of useState / Overhead (100 blocks <p> / 10 components)
+100 | x Per-key
+    |
+    |
+    ...
+    |
+    |
+    |
+    |
+ 10 |  x Per-component
+    |
+  1 |                                           x Centralized
+    |-------------------------------------------------------->
+    0                                          900     1000
+           % of unused content (Based on 10 unique pages)
+
+```
+
+Równolegle, powinieneś wiedzieć, że gdy dynamicznie ładujesz zawartość (`await import()`), skończysz z dodatkowymi żądaniami do serwera. Jedno dodatkowe `useState` lub hook odnosi się do jednego dodatkowego żądania do serwera.
+
+> Aby naprawić ten punkt, Intlayer sugeruje grupowanie wielu definicji zawartości pod tym samym kluczem, Intlayer będzie wtedy scalać tę zawartość.
+
+### Dlaczego zatem podejście scentralizowane jest tak popularne?
+
+- Najpierw, i18next była pierwszym rozwiązaniem, które stało się szeroko stosowane, podążając za podejściem inspirowanym PHP i Java, które opierają się na wyraźnej separacji obaw (MVP). i18next przybył nawet przed trendem frameworków frontendowych i architektury opartej na komponentach.
+- Następnie, gdy biblioteka jest szeroko przyjęta, trudno jest przesunąć ekosystem do innych wzorców.