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

package/docs/ko/autoFill.md

@@ -28,6 +28,53 @@ history:
 author: aymericzip
 ---
 
+# 콘텐츠 선언 파일 번역 채우기
+
+**CI에서 콘텐츠 선언 파일 자동 채우기**는 개발 워크플로우를 가속화하는 방법입니다.
+
+## 동작 이해하기
+
+`fill` 명령은 두 가지 모드를 포함합니다:
+
+- **Complete**: 각 로케일에 대해 누락된 모든 콘텐츠를 자동으로 채우고 현재 파일을 편집하거나, 지정된 경우 다른 파일을 편집합니다. 즉, complete 모드는 이미 번역된 경우 기존 콘텐츠의 번역을 건너뜁니다.
+- **Review**: 각 로케일에 대해 **모든** 콘텐츠를 자동으로 채우고 특정 파일에 대해 생성하거나, 지정된 경우 다른 파일을 생성합니다.
+
+`fill` 명령은 모든 로케일 콘텐츠 선언 파일을 처리합니다. 즉, CMS의 원격 콘텐츠는 처리하지 않습니다. CMS는 자체 번역 관리를 포함합니다.
+`@intlayer/sync-json-plugin`과 같은 플러그인을 사용하는 경우, Intlayer는 JSON 파일을 로케일 콘텐츠 선언 파일로 변환합니다. 즉, `fill` 명령으로 처리됩니다.
+
+새로 생성된 파일에는 사전 메타데이터로 `filled` 지시사항이 포함됩니다. 이 지시사항은 Intlayer가 파일이 자동으로 채워졌는지 여부를 알고, 존재하는 경우 이 파일을 다시 번역하지 않도록 건너뛰는 데 사용됩니다.
+
+Intlayer는 자동 채우기를 위해 다음 지시사항도 고려합니다:
+
+- `.content.{ts|js|json}` → `fill` 지시사항
+- 구성 파일 `.intlayer.config.ts` → `dictionary.fill` 지시사항
+- 그 외의 경우 기본값으로 `true`로 설정됨
+
+로케일별 콘텐츠 선언 파일의 경우, `true` 지시사항은 `./{{fileName}}.fill.content.json`으로 대체됩니다. 이는 로케일별 콘텐츠 선언 파일이 추가 지역화된 콘텐츠를 받을 수 없기 때문입니다. 따라서 기존 파일을 덮어쓰지 않기 위해 새 파일을 생성합니다.
+
+## Default Behavior
+
+기본적으로 `fill`은 전역적으로 `true`로 설정되어 있으며, 이는 Intlayer가 모든 콘텐츠 파일을 자동으로 채우고 파일 자체를 편집한다는 의미입니다. 이 동작은 여러 방법으로 사용자 정의할 수 있습니다:
+
+### 글로벌 구성 옵션
+
+1. **`fill: true` (기본값)** - 모든 로케일을 자동으로 채우고 현재 파일을 편집합니다
+2. **`fill: false`** - 이 콘텐츠 파일에 대한 자동 채우기를 비활성화합니다
+3. **`fill: "./relative/path/to/file"`** - 현재 파일을 편집하지 않고 현재 파일의 위치를 기반으로 해석되는 상대 경로를 가리켜 지정된 파일을 만들거나 업데이트합니다
+4. **`fill: "/absolute/path/to/file"`** - 현재 파일을 편집하지 않고 기본 디렉토리의 위치를 기반으로 해석되는 상대 경로를 가리켜 지정된 파일을 만들거나 업데이트합니다 (구성 파일 `.intlayer.config.ts`의 `baseDir` 필드)
+5. **`fill: "C:\\absolute\path\to\file"`** - 현재 파일을 편집하지 않고 운영 체제를 기반으로 해석되는 절대 경로를 가리켜 지정된 파일을 만들거나 업데이트합니다
+6. **`fill: { [key in Locales]?: string }`** - 각 로케일에 대해 지정된 파일을 만들거나 업데이트합니다
+
+### v7 동작 변경 사항
+
+v7에서는 `fill` 명령 동작이 업데이트되었습니다:
+
+- **`fill: true`** - 현재 파일을 모든 로케일의 채워진 콘텐츠로 다시 작성합니다
+- **`fill: "path/to/file"`** - 현재 파일을 수정하지 않고 지정된 파일을 채웁니다
+- **`fill: false`** - 자동 채우기를 완전히 비활성화합니다
+
+다른 파일에 쓰기 위해 경로 옵션을 사용할 때, fill 메커니즘은 콘텐츠 선언 파일 간의 _master-slave_ 관계를 통해 작동합니다. 메인(master) 파일이 소스 오브 트루스 역할을 하며, 업데이트될 때 Intlayer는 경로로 지정된 파생(filled) 선언 파일에 자동으로 그 변경 사항을 적용합니다.
+
 # 자동 채우기 콘텐츠 선언 파일 번역
 
 **자동 채우기 콘텐츠 선언 파일**은 개발 워크플로우를 가속화하는 방법입니다.
@@ -88,6 +135,40 @@ Intlayer는 메인 파일에 아직 선언되지 않은 모든 로케일을 채
 
 그 후, 두 선언 파일은 단일 사전으로 병합되어 표준 `useIntlayer("example")` 훅(react) / 컴포저블(vue)을 통해 접근할 수 있습니다.
 
+## 글로벌 설정
+
+`intlayer.config.ts` 파일에서 글로벌 자동 채우기 설정을 구성할 수 있습니다.
+
+```ts fileName="intlayer.config.ts"
+import { type IntlayerConfig, Locales } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+    requiredLocales: [Locales.ENGLISH, Locales.FRENCH],
+  },
+  dictionary: {
+    // 모든 사전에 대해 누락된 번역 자동 생성
+    fill: "./{{fileName}}Filled.content.ts",
+    //
+    // fill: "/messages/{{locale}}/{{key}}/{{fileName}}.content.json",
+    //
+    // fill: true, // "./{{fileName}}.content.json"을 사용하는 것처럼 모든 사전에 대해 누락된 번역 자동 생성
+    //
+    // fill: {
+    //   en: "./{{fileName}}.en.content.json",
+    //   fr: "./{{fileName}}.fr.content.json",
+    //   es: "./{{fileName}}.es.content.json",
+    // },
+  },
+};
+
+export default config;
+```
+
+content 파일의 `fill` 필드를 사용하여 사전별로 세부 조정할 수 있습니다. Intlayer는 먼저 사전별 구성을 고려한 후 글로벌 구성으로 돌아갑니다.
+
 ## 자동 채워진 파일 형식
 
 자동 채워진 선언 파일에 권장되는 형식은 **JSON**으로, 형식 제약을 피하는 데 도움이 됩니다. 그러나 Intlayer는 `.ts`, `.js`, `.mjs`, `.cjs` 및 기타 형식도 지원합니다.

package/docs/ko/benchmark/solid.md

@@ -118,6 +118,28 @@ i18n 누수 문제를 빠르게 파악하기 위해 [여기](https://intlayer.or
 - **Scoped static**: 복잡한 추가 네트워크 요청 없이 코드 구조를 유지(논리적 분리).
 - **Scoped dynamic**: 코드 분할 및 성능을 위한 최선의 접근 방식. 현재 뷰와 활성 로케일에 필요한 것만 로드하여 메모리 사용을 최소화함.
 
+### 측정 내용:
+
+각 스택에 대해 실제 브라우저에서 동일한 다국어 앱을 실행한 후 실제로 전송된 내용과 소요 시간을 기록했습니다. 크기는 **일반적인 웹 압축 후**에 보고되었습니다. 이는 원본 소스 수보다 사람들이 다운로드하는 내용에 더 가깝기 때문입니다.
+
+- **국제화 라이브러리 크기**: 번들링, 트리 셰이킹 및 축소 후 i18n 라이브러리의 크기는 빈 컴포넌트의 제공자 + 훅/프리미티브 코드의 크기입니다. 여기에는 번역 파일 로딩이 포함되지 않습니다. 콘텐츠가 들어오기 전에 라이브러리가 얼마나 비싼지 답변합니다.
+
+- **페이지당 JavaScript**: 각 벤치마크 경로의 경우, 그 방문 시 브라우저가 가져오는 스크립트의 양은 스위트의 페이지 전체에서 평균화됩니다(보고서가 롤업하는 로케일 전체). 무거운 페이지는 느린 페이지입니다.
+
+- **다른 로케일의 누수**: 감사된 페이지에 실수로 로드되는 다른 언어의 동일 페이지 콘텐츠입니다. 이 콘텐츠는 불필요하며 피해야 합니다. (예: `/en/about` 페이지 번들의 `/fr/about` 페이지 콘텐츠)
+
+- **다른 경로의 누수**: **다른 화면**의 경우 동일한 개념입니다. 한 페이지만 열었을 때 해당 사본이 함께 로드되는지 여부입니다. (예: `/en/contact` 페이지 번들의 `/en/about` 페이지 콘텐츠). 높은 점수는 약한 분할이나 과도하게 광범위한 번들을 의미합니다.
+
+- **평균 컴포넌트 번들 크기**: 일반적인 UI 조각은 하나의 거대한 앱 번호 내에 숨기는 대신 **한 번에 하나씩** 측정됩니다. 국제화가 일반적인 컴포넌트를 조용히 부풀리는지 여부를 보여줍니다. 예를 들어, 컴포넌트가 다시 렌더링되면 메모리에서 모든 데이터를 로드합니다. 거대한 JSON을 컴포넌트에 연결하는 것은 컴포넌트의 성능을 느리게 할 사용하지 않은 데이터의 큰 저장소를 연결하는 것과 같습니다.
+
+- **언어 전환 반응성**: 앱의 고유한 제어 기능을 사용하여 언어를 전환하고 페이지가 명확하게 전환될 때까지 걸리는 시간을 기록합니다. 이는 방문자가 알아차릴 미시적 단계가 아닌 것입니다.
+
+- **언어 변경 후 렌더링 작업**: 더 좁은 후속 작업입니다. 전환이 진행 중일 때 새로운 언어로 다시 칠하는 데 인터페이스가 소비한 노력입니다. "느껴지는" 시간과 프레임워크 비용이 다를 때 유용합니다.
+
+- **초기 페이지 로드 시간**: 네비게이션에서 브라우저가 테스트한 시나리오에 대해 페이지가 완전히 로드되었다고 간주할 때까지의 시간입니다. 콜드 스타트를 비교하는 데 좋습니다.
+
+- **하이드레이션 시간**: 앱이 노출하는 경우, 클라이언트가 서버 HTML을 실제로 클릭할 수 있는 것으로 변환하는 데 소비하는 시간입니다. 표의 대시는 해당 구현이 이 벤치마크에서 신뢰할 수 있는 하이드레이션 수치를 제공하지 않았음을 의미합니다.
+
 ## GitHub 스타
 
 GitHub 스타는 프로젝트의 인기, 커뮤니티 신뢰 및 장기적인 관련성을 나타내는 강력한 지표입니다. 기술적 품질을 직접적으로 측정하는 것은 아니지만, 얼마나 많은 개발자가 프로젝트가 유용하다고 생각하고 진행 상황을 팔로우하며 채택할 가능성이 있는지를 반영합니다. 프로젝트의 가치를 평가할 때 스타는 대안 간의 견인력을 비교하는 데 도움이 되며 생태계 성장에 대한 통찰력을 제공합니다.

package/docs/ko/benchmark/svelte.md

@@ -116,6 +116,28 @@ i18n 누수 문제를 빠르게 파악하기 위해 [여기](https://intlayer.or
 - **Scoped static**: 복잡한 추가 네트워크 요청 없이 코드 구조를 유지(논리적 분리).
 - **Scoped dynamic**: 코드 분할 및 성능을 위한 최선의 접근 방식. 현재 뷰와 활성 로케일에 필요한 것만 로드하여 메모리 사용을 최소화함.
 
+### 측정한 항목:
+
+동일한 다국어 앱을 모든 스택에서 실제 브라우저로 실행하고, 실제로 전송된 내용과 소요 시간을 기록했습니다. 크기는 **일반적인 웹 압축 후** 보고되며, 이는 원본 소스 크기보다 사용자가 실제로 다운로드하는 내용에 더 가깝습니다.
+
+- **국제화 라이브러리 크기**: 번들링, 트리 쉐이킹 및 최소화 후, i18n 라이브러리의 크기는 빈 컴포넌트의 providers + stores 코드 크기입니다. 번역 파일 로딩은 포함되지 않습니다. 콘텐츠가 포함되기 전 라이브러리의 비용이 어느 정도인지 나타냅니다.
+
+- **페이지당 JavaScript**: 각 벤치마크 경로에 대해 해당 방문에서 브라우저가 가져오는 스크립트의 양입니다. 이는 스위트의 페이지들과 리포트가 롤업하는 로케일들 전체에서 평균화됩니다. 무거운 페이지는 느린 페이지입니다.
+
+- **다른 로케일에서의 누수**: 감사된 페이지에서 실수로 로드될 수 있는 다른 언어의 동일한 페이지 콘텐츠입니다. 이 콘텐츠는 불필요하며 피해야 합니다. (예: `/en/about` 페이지 번들에서 `/fr/about` 페이지 콘텐츠)
+
+- **다른 경로에서의 누수**: **다른 화면**의 경우도 마찬가지입니다. 한 페이지만 열었을 때 해당 복사본이 함께 로드되는지 여부입니다. (예: `/en/contact` 페이지 번들에서 `/en/about` 페이지 콘텐츠). 높은 점수는 약한 분할 또는 과도하게 광범위한 번들을 시사합니다.
+
+- **평균 컴포넌트 번들 크기**: 하나의 거대한 앱 번호 내에 숨겨지지 않고 **한 번에 하나씩** 측정된 일반적인 UI 조각들입니다. 국제화가 일상적인 컴포넌트를 어느 정도 증가시키는지 보여줍니다. 예를 들어, 컴포넌트가 다시 렌더링되면 메모리에서 모든 데이터를 로드합니다. 거대한 JSON을 컴포넌트에 연결하는 것은 컴포넌트의 성능을 느리게 할 거대한 미사용 데이터 저장소를 연결하는 것과 같습니다.
+
+- **언어 전환 반응성**: 앱의 자체 컨트롤을 사용하여 언어를 전환하고 페이지가 명확하게 전환될 때까지의 시간을 측정합니다. 이는 방문자가 눈으로 보게 되는 시간이지, 랩 마이크로 스텝이 아닙니다.
+
+- **언어 변경 후 렌더링 작업**: 더 좁은 후속 조치입니다. 전환이 진행 중인 상태에서 새 언어를 위해 인터페이스가 다시 칠하는 데 소요된 노력의 정도입니다. "느껴지는" 시간과 프레임워크 비용이 다를 때 유용합니다.
+
+- **초기 페이지 로드 시간**: 테스트한 시나리오에 대해 브라우저가 페이지를 완전히 로드된 것으로 간주할 때까지의 시간입니다. 콜드 시작을 비교하는 데 유용합니다.
+
+- **Hydration 시간**: 앱이 노출할 때, 클라이언트가 서버 HTML을 실제로 클릭할 수 있는 것으로 변환하는 데 소요되는 시간입니다. 표의 대시는 해당 구현이 이 벤치마크에서 신뢰할 수 있는 hydration 수치를 제공하지 않음을 의미합니다.
+
 ## GitHub 스타
 
 GitHub 스타는 프로젝트의 인기, 커뮤니티 신뢰 및 장기적인 관련성을 나타내는 강력한 지표입니다. 기술적 품질을 직접적으로 측정하는 것은 아니지만, 얼마나 많은 개발자가 프로젝트가 유용하다고 생각하고 진행 상황을 팔로우하며 채택할 가능성이 있는지를 반영합니다. 프로젝트의 가치를 평가할 때 스타는 대안 간의 견인력을 비교하는 데 도움이 되며 생태계 성장에 대한 통찰력을 제공합니다.

package/docs/ko/benchmark/tanstack.md

@@ -124,6 +124,28 @@ i18n 누수 문제를 빠르게 파악하기 위해 [여기](https://intlayer.or
 - **Scoped static**: 복잡한 추가 네트워크 요청 없이 코드 구조를 유지(논리적 분리).
 - **Scoped dynamic**: 코드 분할 및 성능을 위한 최선의 접근 방식. 현재 뷰와 활성 로케일에 필요한 것만 로드하여 메모리 사용을 최소화함.
 
+### 측정 항목:
+
+모든 스택에 대해 실제 브라우저에서 동일한 다국어 앱을 실행하고, 실제로 전송되는 내용과 소요 시간을 기록했습니다. 크기는 **일반적인 웹 압축 후**에 보고되며, 이는 원본 소스 크기보다 사용자가 다운로드하는 내용에 더 가깝습니다.
+
+- **Internationalization 라이브러리 크기**: 번들링, 트리-셰이킹 및 최소화 후, i18n 라이브러리의 크기는 프로바이더(예: `NextIntlClientProvider`) + 훅(예: `useTranslations`) 코드의 크기를 빈 컴포넌트에서 측정한 것입니다. 번역 파일 로딩은 포함되지 않습니다. 콘텐츠가 들어오기 전에 라이브러리가 얼마나 비용이 드는지를 답합니다.
+
+- **페이지당 JavaScript**: 각 벤치마크 경로에 대해 방문 시 브라우저가 가져오는 스크립트의 양으로, 스위트의 페이지 전체에서 평균화됩니다(리포트가 롤업하는 경우 로케일 전체에서). 무거운 페이지는 느린 페이지입니다.
+
+- **다른 로케일에서의 유출**: 감사된 페이지에 실수로 로드될 수 있는 다른 언어의 동일한 페이지 콘텐츠입니다. 이 콘텐츠는 불필요하며 피해야 합니다. (예: `/en/about` 페이지 번들에서 `/fr/about` 페이지 콘텐츠)
+
+- **다른 경로에서의 유출**: **다른 화면**의 콘텐츠가 한 페이지만 열었을 때 함께 로드되는지 여부에 대한 동일한 개념입니다. (예: `/en/contact` 페이지 번들에서 `/en/about` 페이지 콘텐츠). 높은 점수는 약한 분할 또는 과도하게 넓은 번들을 시사합니다.
+
+- **평균 컴포넌트 번들 크기**: 일반적인 UI 조각들은 한 번에 하나씩 측정되며, 거대한 앱 번호 안에 숨겨지지 않습니다. internationalization이 일상적인 컴포넌트를 조용히 부풀리는지 여부를 보여줍니다. 예를 들어, 컴포넌트가 다시 렌더링되면 메모리에서 모든 데이터를 로드하게 됩니다. 거대한 JSON을 컴포넌트에 연결하는 것은 컴포넌트의 성능을 저하시킬 수 있는 사용되지 않은 데이터의 큰 저장소에 연결하는 것과 같습니다.
+
+- **언어 전환 반응성**: 앱의 자체 컨트롤을 사용하여 언어를 전환하고 페이지가 명확하게 전환될 때까지의 소요 시간을 측정합니다. 방문자가 알 수 있는 수준이며, 실험실 마이크로 단계가 아닙니다.
+
+- **언어 변경 후 렌더링 작업**: 더 좁은 후속 작업으로, 전환이 진행 중일 때 새 언어를 다시 칠하기 위해 인터페이스가 소비한 노력입니다. "느껴지는" 시간과 프레임워크 비용이 다를 때 유용합니다.
+
+- **초기 페이지 로드 시간**: 탐색에서 브라우저가 테스트한 시나리오에 대해 페이지가 완전히 로드되었다고 간주할 때까지의 시간입니다. 콜드 스타트를 비교하는 데 좋습니다.
+
+- **수화 시간**: 앱이 노출할 때, 클라이언트가 서버 HTML을 실제로 클릭할 수 있는 것으로 변환하는 데 소비하는 시간입니다. 테이블의 대시는 해당 구현이 이 벤치마크에서 신뢰할 수 있는 수화 수치를 제공하지 않았음을 의미합니다.
+
 ## GitHub 스타
 
 GitHub 스타는 프로젝트의 인기, 커뮤니티 신뢰 및 장기적인 관련성을 나타내는 강력한 지표입니다. 기술적 품질을 직접적으로 측정하는 것은 아니지만, 얼마나 많은 개발자가 프로젝트가 유용하다고 생각하고 진행 상황을 팔로우하며 채택할 가능성이 있는지를 반영합니다. 프로젝트의 가치를 평가할 때 스타는 대안 간의 견인력을 비교하는 데 도움이 되며 생태계 성장에 대한 통찰력을 제공합니다.

package/docs/ko/cli/ci.md

@@ -140,6 +140,28 @@ steps:
     run: npx intlayer ci fill
 ```
 
+## Scaffolded GitHub Actions
+
+`intlayer init`을 실행하면, Intlayer가 package manager(npm, yarn, pnpm, 또는 bun)를 감지하고 `.github/workflows/` 디렉토리 아래에 해당 package manager와 일치하는 명령어를 포함한 두 개의 GitHub Actions 워크플로우를 생성합니다:
+
+- **`intlayer-fill.yml`** — 모든 pull request에서 dictionaries를 빌드하고 `intlayer fill --git-diff --mode complete`을 실행하여 변경된 dictionaries에 대한 누락된 번역을 생성한 후, 결과를 PR 브랜치에 커밋합니다.
+- **`intlayer-test.yml`** — 모든 pull request에서 dictionaries를 빌드하고 `intlayer test`를 실행하여, 필수 locales에 번역이 누락된 경우 체크를 실패합니다.
+
+기존 워크플로우 파일은 절대 덮어씌워지지 않습니다. scaffolding을 완전히 건너뛰려면, 다음을 실행합니다:
+
+```bash
+npx intlayer init --no-github-actions
+```
+
+### fill 워크플로우에 AI 접근 제공
+
+스캐폴드된 `intlayer-fill.yml`은 AI 접근이 필요합니다. 두 가지 옵션을 사용할 수 있습니다(워크플로우의 `env` 블록에서 구성):
+
+1. **자신의 AI provider 키** — 리포지토리 설정(Settings → Secrets and variables → Actions)에서 `AI_API_KEY` secret을 추가합니다. 워크플로우는 `--provider`, `--model`, `--api-key`를 통해 이를 전달합니다.
+2. **Intlayer CMS 접근 키** — `INTLAYER_CLIENT_ID` 및 `INTLAYER_CLIENT_SECRET` secret을 추가하고 `intlayer.config` `editor` 섹션에 연결합니다. CMS 접근 키는 Intlayer backend을 통해 AI 접근을 제공합니다.
+
+`intlayer-test.yml` 워크플로우는 AI 접근이 필요하지 않습니다.
+
 ## 오류 처리
 
 - `INTLAYER_PROJECT_CREDENTIALS`가 설정되지 않은 경우, 명령어는 오류로 종료됩니다.

package/docs/ko/cli/fill.md

@@ -47,6 +47,14 @@ bun x intlayer fill
 - 기존 번역을 덮어쓰지 않아 기존 번역을 보존합니다.
 - 큐 시스템을 사용하여 파일, 청크 및 로케일을 병렬로 처리하여 속도를 높입니다.
 
+## 주요 포인트:
+
+- 대규모 JSON 파일을 청크로 분할하여 AI 모델의 컨텍스트 윈도우 제한 내에 유지합니다.
+- 출력 형식이 올바르지 않으면 번역을 다시 시도합니다.
+- 번역 정확도 향상을 위해 애플리케이션 및 파일별 컨텍스트를 통합합니다.
+- 기존 번역을 덮어쓰지 않음으로써 보존합니다.
+- 큐 시스템을 사용하여 파일, 청크 및 로케일을 병렬로 처리하여 속도를 높입니다.
+
 ## 별칭:
 
 - `npx intlayer dictionaries fill`

package/docs/ko/cli/login.md

@@ -78,42 +78,6 @@ bun x intlayer login --cms-url https://intlayer.org
 
 ### 구성 옵션
 
-일반적인 구성 옵션도 사용할 수 있습니다:
-
-- `--env-file <path>`: 환경 파일의 경로
-- `-e, --env <env>`: 실행 환경
-- `--base-dir <dir>`: 프로젝트의 기본 디렉터리
-- `--verbose`: 자세한 출력 활성화 (기본값: true)
-- `--prefix <prefix>`: 로그 접두사
-
-## 동작 방식
-
-1. **로컬 서버 시작**: 명령은 CMS로부터 자격증명을 수신하기 위해 무작위 포트에서 로컬 HTTP 서버를 시작합니다
-
-인증을 위해 연결할 Intlayer CMS의 URL을 지정합니다.
-
-- **형식**: `string`
-- **기본값**: `intlayer.config.*`에 구성된 값 또는 `https://intlayer.org`
-- **예제**:
-
-```bash packageManager="npm"
-npx intlayer login --cms-url https://intlayer.org
-```
-
-```bash packageManager="yarn"
-yarn intlayer login --cms-url https://intlayer.org
-```
-
-```bash packageManager="pnpm"
-pnpm intlayer login --cms-url https://intlayer.org
-```
-
-```bash packageManager="bun"
-bun x intlayer login --cms-url https://intlayer.org
-```
-
-### 구성 옵션
-
 다음과 같은 공통 구성 옵션도 사용할 수 있습니다:
 
 - `--env-file <path>`: 환경 파일의 경로

package/docs/ko/compat/i18n-js.md

@@ -0,0 +1,44 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "i18n-js에서 Intlayer로 마이그레이션"
+description: "compat adapter를 사용하여 애플리케이션을 i18n-js에서 Intlayer로 마이그레이션하는 방법을 알아보세요."
+keywords:
+  - i18n-js
+  - intlayer
+  - migration
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - i18n-js
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# i18n-js에서 Intlayer로 마이그레이션
+
+`i18n-js` 라이브러리에서 Intlayer로 전환하는 것은 큰 translations 설정을 Intlayer의 구조화된 파일 resolution 시스템으로 offload하도록 설계된 고도로 최적화된 마이그레이션입니다.
+
+## 해야 할 일
+
+리포지토리에서 다음 설정 명령을 실행하세요:
+
+```bash
+npx intlayer init
+```
+
+`intlayer.config.ts`가 준비되면 bundler 설정에 Intlayer alias를 추가하여 `i18n-js`의 모든 imports가 compat package `@intlayer/i18n-js`를 대상으로 하도록 할 수 있습니다.
+
+## 내부적으로 어떻게 작동하는지
+
+`i18n-js`는 `i18n.t('scope.key', {name})`과 같은 표현식을 통해 namespaces에 접근하며, locale fallbacks와 특정 plural mappings과 함께 합니다.
+
+내부적으로:
+
+- **Interpolation:** compat adapter는 `%{name}` mappings을 targeted runtime dictionary value로 쉽게 파싱합니다.
+- **Pluralization:** `one/other` subkeys를 교체하고 Intlayer의 강력한 underlying plural mechanisms (`Intl.PluralRules`)에 대해 매핑하여 수동 mappings을 추상화합니다.
+- **Locales:** bootstrap 시점에 monolithic language payloads를 로드하는 대신 dictionaries는 native Intlayer 설정을 통해 현재 context 설정에 따라 최적으로 제공됩니다.

package/docs/ko/compat/i18next.md

@@ -0,0 +1,59 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "i18next에서 Intlayer로 마이그레이션"
+description: "compat adapter를 사용하여 Vanilla JS/TS 애플리케이션을 i18next에서 Intlayer로 마이그레이션하는 방법을 알아보세요."
+keywords:
+  - i18next
+  - vanilla
+  - javascript
+  - typescript
+  - intlayer
+  - 마이그레이션
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - i18next
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# i18next에서 Intlayer로 마이그레이션
+
+상세한 단계별 튜토리얼은 [i18next 마이그레이션 가이드](../migration_from_i18next_to_intlayer.md)를 참고하세요.
+
+Intlayer는 `i18next`의 핵심 런타임 특성을 완벽하게 복제합니다. compat package를 활용하면 Vanilla 애플리케이션이나 내부 모듈에서 익숙한 구문을 계속 사용할 수 있습니다.
+
+## 수행할 작업
+
+먼저 프로젝트에서 Intlayer를 초기화하세요:
+
+```bash
+npx intlayer init
+```
+
+Vite를 사용 중인 경우 Intlayer plugin을 포함하여 import를 `@intlayer/i18next`로 라우팅하세요:
+
+```typescript fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import { i18nextVitePlugin } from "@intlayer/i18next/plugin";
+
+export default defineConfig({
+  plugins: [i18nextVitePlugin()],
+});
+```
+
+## 내부 동작 원리
+
+`i18nextVitePlugin`은 `i18next` import를 `@intlayer/i18next`로 별칭 지정하여 JSON 파일 포함으로 인한 bundle 팽창을 방지합니다.
+
+내부적으로:
+
+- **Instance 구성:** `createInstance`는 namespace fallback을 올바르게 파싱하고 적용하며 dictionary 검색을 위해 Intlayer의 컴파일 파이프라인을 활용합니다.
+- **Interpolation:** `{{name}}` 대체 및 `$t(key)` nesting 재귀에 대한 기본 지원.
+- **Context & Plurals:** `key_male` 및 `key_one`/`key_other` 같은 접미사 형식을 식별하고 해결하며 표준 `Intl.PluralRules`에 대해 평가합니다.
+- **Return objects:** `returnObjects: true` 모드는 Intlayer dictionary에서 트리를 안전하게 추출합니다.

package/docs/ko/compat/index.md

@@ -0,0 +1,51 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Intlayer Compat Adapters"
+description: "compat adapter를 사용하여 기존 i18n 솔루션을 Intlayer로 마이그레이션하세요."
+keywords:
+  - compat
+  - 마이그레이션
+  - 국제화
+  - i18n
+  - Intlayer
+slugs:
+  - doc
+  - compatibility
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# Intlayer Compat Adapters
+
+대규모 애플리케이션을 새로운 국제화 라이브러리로 마이그레이션하는 것은 어려울 수 있습니다. 이 전환을 쉽게 하기 위해 Intlayer는 에코시스템에서 가장 인기 있는 i18n 라이브러리를 위한 **compat adapter**를 제공합니다.
+
+이 adapter package들은 기존 i18n 라이브러리와 **동일한 공개 API**를 노출하지만, 런타임에 모든 번역 작업을 Intlayer에 위임합니다.
+
+## 작동 방식
+
+compat adapter를 사용할 때, 애플리케이션의 import를 다시 작성하거나 번역 hook 및 component 사용 방법을 변경할 필요가 없습니다. 대신 Intlayer의 bundler plugin이 기존 import를 자동으로 Intlayer compat package로 별칭 지정합니다.
+
+예를 들어, 개발자가 `import { useTranslation } from 'react-i18next'`를 `import { useTranslation } from '@intlayer/react-i18next'`로 대체하면(bundler plugin을 통해 자동으로 수행됨), 앱은 Intlayer 사전에서 제공되는 번역과 함께 계속 작동합니다. 키도 Intlayer 사전에 대해 타입이 지정됩니다!
+
+## 사용 가능한 Compat Adapters
+
+아래에서 기존 라이브러리를 선택하여 원활하게 마이그레이션하는 방법을 확인하세요:
+
+- [Vue I18n](./vue-i18n.md)
+- [Transloco](./transloco.md)
+- [React Intl](./react-intl.md)
+- [Svelte I18n](./svelte-i18n.md)
+- [React i18next](./react-i18next.md)
+- [Polyglot.js](./polyglot.md)
+- [NuxtJS I18n](./nuxtjs-i18n.md)
+- [NGX Translate](./ngx-translate.md)
+- [Next Translate](./next-translate.md)
+- [Next Intl](./next-intl.md)
+- [Next i18next](./next-i18next.md)
+- [i18next](./i18next.md)
+- [Lingui](./lingui.md)
+- [I18n-js](./i18n-js.md)

package/docs/ko/compat/lingui.md

@@ -0,0 +1,44 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Lingui에서 Intlayer로 마이그레이션"
+description: "compat adapter를 사용하여 애플리케이션을 Lingui에서 Intlayer로 마이그레이션하는 방법을 알아보세요."
+keywords:
+  - lingui
+  - intlayer
+  - migration
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - lingui
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# Lingui에서 Intlayer로 마이그레이션
+
+프로젝트가 현재 Lingui의 macro 기반 컴파일에 의존하고 있다면 Intlayer로 전환하면 강력한 macro workflows를 유지하면서 네이티브로 Intlayer의 JSON compilation strategy를 지원할 수 있습니다.
+
+## 해야 할 일
+
+프로젝트에서 Intlayer를 초기화하여 시작하세요:
+
+```bash
+npx intlayer init
+```
+
+`intlayer.config.ts`가 생성됩니다. build step에서 `@lingui/babel-plugin-lingui-macro` / `@lingui/swc-plugin`을 유지하여 Intlayer compiler _이전에_ 실행되도록 하세요. 그런 다음 bundler plugin alias를 사용하여 `@lingui/core`과 `@lingui/react`을 `@intlayer/lingui`로 라우팅하세요.
+
+## 내부적으로 어떻게 작동하는지
+
+Lingui는 macros (`` t`Hello ${name}` ``과 `<Trans>` 같은)를 사용하며, 이는 `i18n._(id, values)` 같은 runtime 호출로 컴파일됩니다.
+
+내부적으로:
+
+- **Macros:** 이전과 정확히 동일하게 컴파일되어 소스 구문에 중단이 없음을 보장합니다.
+- **Runtime translation:** aliased `i18n._()`은 Intlayer dictionaries를 사용합니다. 명시적으로 이름이 지정된 IDs와 hashed IDs 모두 Intlayer의 `.po` sync plugins을 사용하여 완전히 매핑되며 keys를 안전하게 aggregate하고 prune합니다.
+- **ICU capabilities:** pluralization, selection, ICU variants에 대한 지원은 Intlayer의 unified ICU parser 덕분에 강력하게 유지되어 동일한 렌더링 출력을 보장합니다.

package/docs/ko/compat/next-i18next.md

@@ -0,0 +1,55 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "next-i18next에서 Intlayer로 마이그레이션"
+description: "compat adapter를 사용하여 Next.js 애플리케이션을 next-i18next에서 Intlayer로 마이그레이션하는 방법을 알아보세요."
+keywords:
+  - next-i18next
+  - nextjs
+  - intlayer
+  - migration
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - next-i18next
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# next-i18next에서 Intlayer로 마이그레이션
+
+Intlayer는 모든 Next.js Pages Router 및 App Router 구현을 투명하게 처리합니다. adapter를 사용하면 코드를 전혀 다시 작성하지 않고 `next-i18next` 구현을 마이그레이션할 수 있습니다.
+
+## 해야 할 일
+
+시작하려면 다음을 실행하세요:
+
+```bash
+npx intlayer init
+```
+
+필요한 Intlayer 설정 파일을 만듭니다. 백그라운드에서 Intlayer로 변경하려면 `next.config.ts`를 업데이트하세요:
+
+```typescript fileName="next.config.ts"
+import type { NextConfig } from "next";
+import { createNextI18nPlugin } from "@intlayer/next-i18next/plugin";
+
+const withIntlayer = createNextI18nPlugin();
+
+const nextConfig: NextConfig = {};
+
+export default withIntlayer(nextConfig);
+```
+
+## 내부적으로 어떻게 작동하는지
+
+`createNextI18nPlugin`은 Next.js의 네이티브 동작과 core `next-intlayer` plugin을 구성하여 `next-i18next`, `react-i18next`, `i18next`에 대한 모든 필요한 Webpack/Turbopack aliases를 주입합니다.
+
+내부적으로:
+
+- **`serverSideTranslations` & `appWithTranslation`:** 이제 Intlayer의 내부 loaders를 위한 wrapper 함수로 작동하여 대규모 정적 JSON injection을 우회합니다.
+- **Client hooks:** 즉시 `@intlayer/react-i18next`로 위임하여 모든 formatting, plurals, nested namespace 기능을 유지합니다.

package/docs/ko/compat/next-intl.md

@@ -0,0 +1,59 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "next-intl에서 Intlayer로 마이그레이션"
+description: "compat adapter를 사용하여 Next.js 애플리케이션을 next-intl에서 Intlayer로 마이그레이션하는 방법을 알아보세요."
+keywords:
+  - next-intl
+  - nextjs
+  - intlayer
+  - migration
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - next-intl
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# next-intl에서 Intlayer로 마이그레이션
+
+완전하고 상세한 단계별 튜토리얼을 보려면 전체 [next-intl 마이그레이션 가이드](../migration_from_next-intl_to_intlayer.md)를 참조하세요.
+
+`next-intl`에서 Intlayer로 마이그레이션하면 애플리케이션의 라우팅과 구문을 완전히 유지할 수 있습니다.
+
+## 해야 할 일
+
+리포지토리에서 다음 명령을 실행하세요:
+
+```bash
+npx intlayer init
+```
+
+이렇게 하면 `intlayer.config.ts`가 생성됩니다. `next.config.ts`에서 plugin wrapper를 사용하여 `next-intl` aliases를 `@intlayer/next-intl`로 완벽하게 주입합니다.
+
+```typescript fileName="next.config.ts"
+import type { NextConfig } from "next";
+import { createNextIntlPlugin } from "@intlayer/next-intl/plugin";
+
+const withIntlayer = createNextIntlPlugin();
+
+const nextConfig: NextConfig = {};
+
+export default withIntlayer(nextConfig);
+```
+
+## 내부적으로 어떻게 작동하는지
+
+bundler wrapper는 번역을 교체하지만 **`next-intl/navigation` 기능은 그대로 유지합니다** (예: `Link`, `redirect`, `usePathname`).
+
+내부적으로:
+
+- **ICU runtime:** Plurals (`=0`, `one`, `other`), select/selectordinal, `#` arguments, formatted args (`{ts, date, long}`)는 공유 `resolveMessage(..., 'icu')` resolver를 사용하여 올바르게 실행됩니다.
+- **`useTranslations()` & `getTranslations()`:** bare scope 호출은 첫 번째 key segment를 올바른 dictionary identifier로 추출합니다. Nested namespaces는 dictionary paths와 prefixes로 우아하게 분할됩니다.
+- **Rich formatting:** `t.rich()`와 `t.markup()` 모두 완전히 네이티브로 구현되어 HTML 같은 노드를 렌더링된 React chunks로 변환합니다.
+- **`useFormatter`:** `relativeTime`, `list`, `dateTimeRange`, 설정의 named formats는 core native `Intl` formatters로 연결됩니다.

package/docs/ko/compat/next-translate.md

@@ -0,0 +1,45 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Next Translate에서 Intlayer로 마이그레이션"
+description: "compat adapter를 사용하여 Next.js 애플리케이션을 next-translate에서 Intlayer로 마이그레이션하는 방법을 알아보세요."
+keywords:
+  - next-translate
+  - nextjs
+  - intlayer
+  - migration
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - next-translate
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# Next Translate에서 Intlayer로 마이그레이션
+
+`next-translate`에서 Intlayer로의 마이그레이션은 기존 구문과 tags를 유지하는 거의 drop-in 대체입니다.
+
+## 해야 할 일
+
+프로젝트에서 Intlayer를 초기화하세요:
+
+```bash
+npx intlayer init
+```
+
+CLI는 설정을 scaffold합니다. 그런 다음 Intlayer plugin을 `next.config.ts`에 적용할 수 있으며, 이는 `next-translate/useTranslation`을 `@intlayer/next-translate`로 매핑하는 build-time subpath aliases를 주입합니다.
+
+## 내부적으로 어떻게 작동하는지
+
+`next-translate`는 `useTranslation('ns')`, `t('ns:key.path')`, `<Trans>` 컴포넌트 같은 hooks를 제공합니다.
+
+내부적으로:
+
+- **Interpolation & Plurals:** `react-i18next` adapter 동작에 매우 유사합니다. 동적으로 처리되는 것은 `{{var}}` placeholders와 `key_0`, `key_one`, `key_other` 같은 suffixes로부터 매핑된 pluralization입니다.
+- **`<Trans>` component:** HTML 같은 tag parsing과 array 기반 `components` prop과 함께 직접 지원됩니다.
+- **Namespaces:** Subpath aliasing은 수동 수정 없이 `useTranslation` 참조가 올바른 내부 dictionary namespaces를 참조하도록 보장합니다.