@intlayer/docs 7.2.3 → 7.3.0

package/docs/ko/cli/test.md

@@ -0,0 +1,76 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-11-22
+title: 누락된 번역 테스트
+description: 사전에서 누락된 번역을 테스트하고 식별하는 방법을 알아보세요.
+keywords:
+  - 테스트
+  - 누락된 번역
+  - CLI
+  - Intlayer
+slugs:
+  - doc
+  - concept
+  - cli
+  - test
+---
+
+# 누락된 번역 테스트
+
+```bash
+npx intlayer content test
+```
+
+## 별칭:
+
+- `npx intlayer test`
+
+이 명령어는 모든 구성된 로케일에서 누락된 번역을 식별하기 위해 콘텐츠 선언 파일을 분석합니다. 어떤 번역 키가 어떤 로케일에서 누락되었는지에 대한 포괄적인 보고서를 제공하여 다국어 콘텐츠의 일관성을 유지하는 데 도움을 줍니다.
+
+## 예시 출력:
+
+```bash
+pnpm intlayer content test
+Missing translations:
+ - home-page                      - tr         - src/components/HomePage/homePage.content.ts
+ - server-component               - es, tr     - src/components/ServerComponent/serverComponent.content.ts
+ - client-component               - pl, tr     - src/components/ClientComponent/clientComponent.content.ts
+Locales: en, ru, ja, fr, ko, zh, es, de, ar, it, en-GB, pt, hi, tr, pl
+Required locales: en
+Missing locales: pl, tr, es
+Missing required locales: -
+Total missing locales: 3
+Total missing required locales: 0
+```
+
+## 인수:
+
+**구성 옵션:**
+
+- **`--env`**: 환경을 지정합니다 (예: `development`, `production`).
+- **`--env-file [envFile]`**: 변수 로드를 위한 사용자 지정 환경 파일을 제공합니다.
+- **`--base-dir`**: 프로젝트의 기본 디렉터리를 지정합니다.
+
+  > 예시: `npx intlayer content test --base-dir ./src --env-file .env.production.local`
+
+- **`--no-cache`**: 캐시를 비활성화합니다.
+
+  > 예시: `npx intlayer build --no-cache`
+
+**준비 옵션:**
+
+- **`--build`**: 푸시 전에 사전을 빌드하여 콘텐츠가 최신 상태인지 확인합니다. true는 빌드를 강제하고, false는 빌드를 건너뛰며, undefined는 빌드 캐시를 사용하도록 허용합니다.
+
+**로그 옵션:**
+
+- **`--verbose`**: 디버깅을 위한 상세 로그를 활성화합니다. (CLI에서 기본값은 true)
+
+  > 예시: `npx intlayer content test --verbose`
+
+## 예시:
+
+```bash
+npx intlayer content test --verbose
+```
+
+출력 결과는 모든 구성된 로케일에서 애플리케이션이 제대로 작동하도록 완료해야 할 번역을 빠르게 식별하는 데 도움이 됩니다.

package/docs/ko/cli/transform.md

@@ -0,0 +1,65 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-11-22
+title: 컴포넌트 변환
+description: 기존 컴포넌트를 Intlayer로 변환하는 방법을 알아보세요.
+keywords:
+  - 변환
+  - 컴포넌트
+  - 마이그레이션
+  - CLI
+  - Intlayer
+slugs:
+  - doc
+  - concept
+  - cli
+  - transform
+---
+
+# 컴포넌트 변환
+
+```bash
+npx intlayer transform
+```
+
+이 명령어는 코드 파일을 분석하여 기존 컴포넌트를 Intlayer로 마이그레이션하는 데 도움을 줍니다. 대화형 파일 선택 또는 특정 파일 지정 방식을 지원합니다.
+
+## 별칭:
+
+- `npx intlayer trans`
+
+## 인수:
+
+**파일 선택 옵션:**
+
+- **`-f, --file [files...]`**: 변환할 특정 파일 목록입니다. 지정하지 않으면 CLI가 일치하는 파일(`**/*.{tsx,jsx,vue,svelte,ts,js}`)을 검색하고 변환할 파일을 선택하도록 안내합니다.
+
+> 예시: `npx intlayer transform -f src/components/MyComponent.tsx`
+
+**출력 옵션:**
+
+- **`-o, --output-content-declarations [outputContentDeclarations]`**: 생성된 콘텐츠 선언 파일을 저장할 디렉토리입니다.
+
+  > 예시: `npx intlayer transform -o src/content`
+
+- **`--code-only`**: 컴포넌트 코드만 변환합니다 (콘텐츠 선언은 작성하지 않음).
+
+  > 예시: `npx intlayer transform --code-only`
+
+- **`--declaration-only`**: 콘텐츠 선언만 생성합니다 (컴포넌트는 다시 작성하지 않음).
+
+  > 예시: `npx intlayer transform --declaration-only`
+
+**구성 옵션:**
+
+- **`--base-dir`**: 프로젝트의 기본 디렉토리를 지정합니다.
+- **`--env`**: 환경을 지정합니다.
+- **`--env-file`**: 사용자 정의 환경 파일을 제공합니다.
+- **`--verbose`**: 자세한 로깅을 활성화합니다.
+
+**필수 플러그인:**
+
+transform 명령어는 TypeScript / JSX 파일에서는 추가 플러그인 없이 작동합니다. 그러나 Vue 및 Svelte 프로젝트에서는 다음 플러그인들이 설치되어 있어야 합니다:
+
+- **`@intlayer/vue-transformer`**: Vue 파일용.
+- **`@intlayer/svelte-transformer`**: Svelte 파일용.

package/docs/ko/cli/version.md

@@ -0,0 +1,24 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-11-22
+title: CLI 버전 확인
+description: 설치된 Intlayer CLI 버전을 확인하는 방법을 알아보세요.
+keywords:
+  - 버전
+  - CLI
+  - Intlayer
+slugs:
+  - doc
+  - concept
+  - cli
+  - version
+---
+
+# CLI 버전 확인
+
+```bash
+npx intlayer --version
+npx intlayer version
+```
+
+두 명령어 모두 설치된 Intlayer CLI 버전을 출력합니다.

package/docs/ko/cli/watch.md

@@ -0,0 +1,37 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-11-22
+title: 사전 감시
+description: 콘텐츠 선언 파일의 변경 사항을 감시하고 자동으로 사전을 빌드하는 방법을 알아보세요.
+keywords:
+  - 감시
+  - 사전
+  - CLI
+  - Intlayer
+slugs:
+  - doc
+  - concept
+  - cli
+  - watch
+---
+
+# 사전 감시
+
+```bash
+npx intlayer watch
+```
+
+이 명령어는 콘텐츠 선언 파일의 변경 사항을 감시하고 `.intlayer` 디렉토리에 사전을 빌드합니다.
+이 명령어는 `npx intlayer build --watch --skip-prepare`와 동일합니다.
+
+## 별칭:
+
+- `npx intlayer dictionaries watch`
+- `npx intlayer dictionary watch`
+- `npx intlayer dic watch`
+
+## 인수:
+
+- **`--with`**: 감시와 병렬로 명령어를 시작합니다.
+
+> 예시: `npx intlayer watch --with "next dev --turbopack"`

package/docs/ko/packages/intlayer/getPrefix.md

@@ -0,0 +1,213 @@
+---
+createdAt: 2025-11-16
+updatedAt: 2025-11-16
+title: getPrefix 함수 문서 | intlayer
+description: intlayer 패키지의 getPrefix 함수 사용법을 확인하세요
+keywords:
+  - getPrefix
+  - prefix
+  - Intlayer
+  - intlayer
+  - 국제화
+  - 문서
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - packages
+  - intlayer
+  - getPrefix
+history:
+  - version: 7.1.0
+    date: 2025-11-16
+    changes: 초기 문서화
+---
+
+# 문서: `intlayer`의 `getPrefix` 함수
+
+## 설명
+
+`getPrefix` 함수는 라우팅 모드 설정에 따라 주어진 로케일의 URL 접두사를 결정합니다. 로케일을 기본 로케일과 비교하고, 유연한 URL 구성을 위해 세 가지 다른 접두사 형식을 포함하는 객체를 반환합니다.
+
+**주요 기능:**
+
+- 첫 번째 매개변수로 로케일을 받음 (필수)
+- `defaultLocale`과 `mode`를 포함하는 선택적 `options` 객체
+- `prefix`와 `localePrefix` 속성을 가진 객체를 반환
+- 모든 라우팅 모드 지원: `prefix-no-default`, `prefix-all`, `no-prefix`, `search-params`
+- 로케일 접두사를 추가할 시점을 결정하는 가벼운 유틸리티
+
+---
+
+## 함수 시그니처
+
+```typescript
+getPrefix(
+  locale: Locales,               // 필수
+  options?: {                    // 선택적
+    defaultLocale?: Locales;
+    mode?: 'prefix-no-default' | 'prefix-all' | 'no-prefix' | 'search-params';
+  }
+): GetPrefixResult
+
+type GetPrefixResult = {
+  prefix: string;   // 예: 'fr/' 또는 ''
+  localePrefix?: Locale; // 예: 'fr' 또는 undefined
+}
+```
+
+---
+
+## 매개변수
+
+- `locale: Locales`
+  - **설명**: 접두사를 생성할 로케일입니다. 값이 falsy(정의되지 않음, null, 빈 문자열)인 경우 함수는 빈 문자열을 반환합니다.
+  - **타입**: `Locales`
+  - **필수**: 예
+
+- `options?: object`
+  - **설명**: 접두사 결정에 대한 구성 객체입니다.
+  - **타입**: `object`
+  - **필수**: 아니요 (선택 사항)
+
+  - `options.defaultLocale?: Locales`
+    - **설명**: 애플리케이션의 기본 로케일입니다. 제공되지 않으면 프로젝트 구성에서 설정된 기본 로케일을 사용합니다.
+    - **타입**: `Locales`
+    - **기본값**: [`프로젝트 구성`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/configuration.md#middleware)
+
+  - `options.mode?: 'prefix-no-default' | 'prefix-all' | 'no-prefix' | 'search-params'`
+
+- **설명**: 로케일 처리를 위한 URL 라우팅 모드입니다. 제공되지 않으면 프로젝트 구성에서 설정된 모드를 사용합니다.
+- **타입**: `'prefix-no-default' | 'prefix-all' | 'no-prefix' | 'search-params'`
+- **기본값**: [`프로젝트 구성`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/configuration.md#middleware)
+- **모드**:
+  - `prefix-no-default`: 로케일이 기본 로케일과 일치할 때 빈 문자열을 반환합니다.
+  - `prefix-all`: 기본 로케일을 포함한 모든 로케일에 대해 접두사를 반환합니다.
+  - `no-prefix`: 빈 문자열을 반환합니다 (URL에 접두사가 없음).
+  - `search-params`: 빈 문자열을 반환합니다 (로케일이 쿼리 매개변수에 있음).
+
+### 반환값
+
+- **타입**: `GetPrefixResult`
+- **설명**: 세 가지 다른 접두사 형식을 포함하는 객체:
+  - `prefix`: 후행 슬래시가 포함된 경로 접두사 (예: `'fr/'`, `''`)
+  - `localePrefix`: 슬래시가 없는 로케일 식별자 (예: `'fr'`, `undefined`)
+
+---
+
+## 사용 예제
+
+### 기본 사용법
+
+```typescript codeFormat="typescript"
+import { getPrefix, Locales } from "intlayer";
+
+// 영어 로케일에 대한 접두사 확인
+getPrefix(Locales.ENGLISH, {
+  defaultLocale: Locales.ENGLISH,
+  mode: "prefix-all",
+});
+// 반환: { prefix: 'en/', localePrefix: 'en' }
+
+// 프랑스어 로케일에 대한 접두사 확인
+getPrefix(Locales.FRENCH, {
+  defaultLocale: Locales.ENGLISH,
+  mode: "prefix-no-default",
+});
+// 반환: { prefix: 'fr/', localePrefix: 'fr' }
+```
+
+```javascript codeFormat="esm"
+import { getPrefix, Locales } from "intlayer";
+
+getPrefix(Locales.ENGLISH, { mode: "prefix-all" });
+javascript codeFormat="commonjs"
+const { getPrefix, Locales } = require("intlayer");
+
+getPrefix(Locales.ENGLISH, { mode: "prefix-all" });
+// 반환: { prefix: '', localePrefix: undefined }
+```
+
+### 다양한 라우팅 모드
+
+```typescript
+import { getPrefix, Locales } from "intlayer";
+
+// prefix-all: 항상 prefix를 반환
+getPrefix(Locales.ENGLISH, {
+  mode: "prefix-all",
+  defaultLocale: Locales.ENGLISH,
+});
+// 반환: { prefix: '/en', localePrefix: 'en' }
+
+// prefix-no-default: 로케일이 기본값과 일치할 때는 prefix 없음
+getPrefix(Locales.ENGLISH, {
+  mode: "prefix-no-default",
+  defaultLocale: Locales.ENGLISH,
+});
+// 반환: { prefix: '', localePrefix: undefined }
+
+javascript;
+// prefix-no-default: 기본 로케일과 다를 경우 접두사를 반환합니다.
+getPrefix(Locales.FRENCH, {
+  mode: "prefix-no-default",
+  defaultLocale: Locales.ENGLISH,
+});
+// 반환값: { prefix: 'fr/', localePrefix: 'fr' }
+
+// no-prefix & search-params: 절대 접두사를 반환하지 않습니다.
+getPrefix(Locales.ENGLISH, { mode: "no-prefix" });
+// 반환값: { prefix: '', localePrefix: undefined }
+
+getPrefix(Locales.ENGLISH, { mode: "search-params" });
+// 반환값: { prefix: '', localePrefix: undefined }
+```
+
+### 실용적인 예제
+
+```typescript
+import { getPrefix, Locales } from "intlayer";
+
+// 특정 로케일에 적합한 접두사를 사용하여 URL을 생성합니다.
+const locale = Locales.FRENCH;
+const { prefix, localePrefix } = getPrefix(locale, {
+  defaultLocale: Locales.ENGLISH,
+  mode: "prefix-no-default",
+});
+
+typescript;
+// 경로 구성을 위한 prefix 사용
+const url1 = `/${prefix}about`.replace(/\/+/g, "/");
+// 결과: "/fr/about"
+
+// locale 식별을 위한 localePrefix 사용
+console.log(`현재 로케일: ${localePrefix}`);
+// 출력: "현재 로케일: fr"
+```
+
+---
+
+## 관련 함수
+
+- [`getLocalizedUrl`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/packages/intlayer/getLocalizedUrl.md): 특정 로케일에 대한 현지화된 URL 생성
+- [`getMultilingualUrls`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/packages/intlayer/getMultilingualUrls.md): 구성된 모든 로케일에 대한 URL 생성
+
+---
+
+## TypeScript
+
+```typescript
+type GetPrefixResult = {
+  prefix: string; // 슬래시가 포함된 경로 접두사 (예: 'fr/' 또는 '')
+  localePrefix?: Locale; // 슬래시 없이 로케일 식별자 (예: 'fr' 또는 undefined)
+};
+
+function getPrefix(
+  locale: Locales,
+  options?: {
+    defaultLocale?: Locales;
+    mode?: "prefix-no-default" | "prefix-all" | "no-prefix" | "search-params";
+  }
+): GetPrefixResult;
+```

package/docs/pl/cli/build.md

@@ -0,0 +1,64 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-11-22
+title: Budowanie słowników
+description: Dowiedz się, jak budować swoje słowniki Intlayer z plików deklaracji treści.
+keywords:
+  - Budowanie
+  - Słowniki
+  - CLI
+  - Intlayer
+slugs:
+  - doc
+  - concept
+  - cli
+  - build
+---
+
+# Budowanie słowników
+
+Aby zbudować swoje słowniki, możesz uruchomić polecenia:
+
+```bash
+npx intlayer build
+```
+
+lub w trybie obserwacji
+
+```bash
+npx intlayer build --watch
+```
+
+To polecenie domyślnie znajdzie Twoje pliki deklaracji treści w ścieżce `./src/**/*.content.{ts|js|mjs|cjs|json|tsx|jsx}` i zbuduje słowniki w katalogu `.intlayer`.
+
+## Alias-y:
+
+- `npx intlayer dictionaries build`
+- `npx intlayer dictionary build`
+- `npx intlayer dic build`
+
+## Argumenty:
+
+- **`--base-dir`**: Określ katalog bazowy dla projektu. Aby pobrać konfigurację intlayer, polecenie będzie szukać pliku `intlayer.config.{ts,js,json,cjs,mjs}` w katalogu bazowym.
+
+  > Przykład: `npx intlayer build --base-dir ./src`
+
+- **`--env`**: Określ środowisko (np. `development`, `production`). Przydatne, gdy używasz zmiennych środowiskowych w pliku konfiguracyjnym intlayer.
+
+  > Przykład: `npx intlayer build --env production`
+
+- **`--env-file`**: Podaj niestandardowy plik środowiskowy do załadowania zmiennych. Przydatne, gdy używasz zmiennych środowiskowych w pliku konfiguracyjnym intlayer.
+
+  > Przykład: `npx intlayer build --env-file .env.production.local`
+
+- **`--with`**: Uruchom polecenie równolegle z budowaniem.
+
+  > Przykład: `npx intlayer build --with "next dev --turbopack"`
+
+- **`--skip-prepare`**: Pomiń krok przygotowania.
+
+  > Przykład: `npx intlayer build --skip-prepare`
+
+- **`--no-cache`**: Wyłącz pamięć podręczną.
+
+  > Przykład: `npx intlayer build --no-cache`

package/docs/pl/cli/configuration.md

@@ -0,0 +1,63 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-11-22
+title: Zarządzanie konfiguracją
+description: Dowiedz się, jak pobrać i przesłać swoją konfigurację Intlayer do CMS.
+keywords:
+  - Konfiguracja
+  - Config
+  - CLI
+  - Intlayer
+  - CMS
+slugs:
+  - doc
+  - concept
+  - cli
+  - configuration
+---
+
+# Zarządzanie konfiguracją
+
+## Pobierz konfigurację
+
+Polecenie `configuration get` pobiera aktualną konfigurację dla Intlayer, w szczególności ustawienia lokalizacji. Jest to przydatne do weryfikacji Twojej konfiguracji.
+
+```bash
+npx intlayer configuration get
+```
+
+## Alias:
+
+- `npx intlayer config get`
+- `npx intlayer conf get`
+
+## Argumenty:
+
+- **`--env`**: Określ środowisko (np. `development`, `production`).
+- **`--env-file`**: Podaj niestandardowy plik środowiskowy do załadowania zmiennych.
+- **`--base-dir`**: Określ katalog bazowy projektu.
+- **`--verbose`**: Włącz szczegółowe logowanie w celu debugowania. (domyślnie true przy użyciu CLI)
+- **`--no-cache`**: Wyłącz pamięć podręczną.
+
+## Prześlij konfigurację
+
+Polecenie `configuration push` przesyła Twoją konfigurację do Intlayer CMS i edytora. Ten krok jest niezbędny, aby umożliwić korzystanie z zewnętrznych słowników w Intlayer Visual Editor.
+
+```bash
+npx intlayer configuration push
+```
+
+## Alias:
+
+- `npx intlayer config push`
+- `npx intlayer conf push`
+
+## Argumenty:
+
+- **`--env`**: Określ środowisko (np. `development`, `production`).
+- **`--env-file`**: Podaj niestandardowy plik środowiskowy do ładowania zmiennych.
+- **`--base-dir`**: Określ katalog bazowy projektu.
+- **`--verbose`**: Włącz szczegółowe logowanie w celu debugowania. (domyślnie true przy użyciu CLI)
+- **`--no-cache`**: Wyłącz pamięć podręczną.
+
+Poprzez przesłanie konfiguracji, Twój projekt jest w pełni zintegrowany z Intlayer CMS, co umożliwia płynne zarządzanie słownikami w zespołach.

package/docs/pl/cli/debug.md

@@ -0,0 +1,46 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-11-22
+title: Debugowanie polecenia Intlayer
+description: Dowiedz się, jak debugować i rozwiązywać problemy z CLI Intlayer.
+keywords:
+  - Debugowanie
+  - Rozwiązywanie problemów
+  - CLI
+  - Intlayer
+slugs:
+  - doc
+  - concept
+  - cli
+  - debug
+---
+
+# Debugowanie polecenia intlayer
+
+## 1. **Upewnij się, że używasz najnowszej wersji**
+
+Uruchom:
+
+```bash
+npx intlayer --version                  # aktualna wersja intlayer dla lokalnej konfiguracji
+npx intlayer@latest --version           # najnowsza dostępna wersja intlayer
+```
+
+## 2. **Sprawdź, czy polecenie jest zarejestrowane**
+
+Możesz to sprawdzić za pomocą:
+
+```bash
+npx intlayer --help                     # Wyświetla listę dostępnych poleceń i informacje o ich użyciu
+npx intlayer dictionary build --help    # Wyświetla listę dostępnych opcji dla polecenia
+```
+
+## 3. **Uruchom ponownie terminal**
+
+Czasami konieczne jest ponowne uruchomienie terminala, aby rozpoznał nowe polecenia.
+
+## 4. **Wyczyść pamięć podręczną npx (jeśli utknąłeś na starszej wersji)**
+
+```bash
+npx clear-npx-cache
+```

package/docs/pl/cli/doc-review.md

@@ -0,0 +1,43 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-11-22
+title: Przegląd dokumentu
+description: Dowiedz się, jak przeglądać pliki dokumentacji pod kątem jakości, spójności i kompletności w różnych lokalizacjach.
+keywords:
+  - Przegląd
+  - Dokument
+  - Dokumentacja
+  - AI
+  - CLI
+  - Intlayer
+slugs:
+  - doc
+  - concept
+  - cli
+  - doc-review
+---
+
+# Przegląd dokumentu
+
+Polecenie `doc review` analizuje pliki dokumentacji pod kątem jakości, spójności i kompletności w różnych lokalizacjach.
+
+```bash
+npx intlayer doc review
+```
+
+Można go użyć do przeglądu plików, które są już przetłumaczone, oraz do sprawdzenia, czy tłumaczenie jest poprawne.
+
+W większości przypadków,
+
+- preferuj użycie `doc translate`, gdy przetłumaczona wersja tego pliku nie jest dostępna.
+- preferuj użycie `doc review`, gdy przetłumaczona wersja tego pliku już istnieje.
+
+> Zauważ, że proces przeglądu zużywa więcej tokenów wejściowych niż proces tłumaczenia, aby w pełni przejrzeć ten sam plik. Jednak proces przeglądu zoptymalizuje fragmenty do przeglądu i pominie części, które nie zostały zmienione.
+
+## Argumenty:
+
+Polecenie `doc review` akceptuje te same argumenty co `doc translate`, co pozwala na przeglądanie konkretnych plików dokumentacji i stosowanie kontroli jakości.
+
+Jeśli aktywowałeś jedną z opcji git, polecenie przejrzy tylko te części plików, które uległy zmianie. Skrypt podzieli plik na fragmenty i przejrzy każdy z nich. Jeśli w danym fragmencie nie ma zmian, skrypt go pominie, aby przyspieszyć proces przeglądu i ograniczyć koszty korzystania z API dostawcy AI.
+
+- Pełną listę argumentów znajdziesz w dokumentacji polecenia [Translate Document](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/cli/doc-translate.md).