@intlayer/docs 5.5.8

package/ko/packages/intlayer/getConfiguration.md

@@ -0,0 +1,120 @@
+# Documentation: `getConfiguration` 함수 in `intlayer`
+
+## 설명
+
+`getConfiguration` 함수는 환경 변수를 추출하여 `intlayer` 애플리케이션의 전체 구성을 가져옵니다. 이 함수는 클라이언트와 서버 측에서 동일한 구성을 사용할 수 있는 유연성을 제공하여 애플리케이션 전반에 걸쳐 일관성을 보장합니다.
+
+---
+
+## 매개변수
+
+이 함수는 매개변수를 받지 않습니다. 대신 환경 변수를 사용하여 구성을 설정합니다.
+
+### 반환값
+
+- **유형**: `IntlayerConfig`
+- **설명**: `intlayer`의 전체 구성을 포함하는 객체입니다. 구성은 다음 섹션을 포함합니다:
+
+  - `internationalization`: 로케일 및 엄격 모드와 관련된 설정.
+  - `middleware`: URL 및 쿠키 관리와 관련된 설정.
+  - `content`: 콘텐츠 파일, 디렉토리 및 패턴과 관련된 설정.
+  - `editor`: 에디터 관련 설정.
+
+자세한 내용은 [Intlayer 구성 문서](https://github.com/aymericzip/intlayer/blob/main/docs/ko/configuration.md)를 참조하세요.
+
+---
+
+## 사용 예제
+
+### 전체 구성 가져오기
+
+```typescript codeFormat="typescript"
+import { getConfiguration } from "intlayer";
+
+const config = getConfiguration();
+console.log(config);
+// 출력:
+// {
+//   internationalization: { ... },
+//   middleware: { ... },
+//   content: { ... },
+//   editor: { ... }
+// }
+```
+
+```javascript codeFormat="esm"
+import { getConfiguration } from "intlayer";
+
+const config = getConfiguration();
+console.log(config);
+// 출력:
+// {
+//   internationalization: { ... },
+//   middleware: { ... },
+//   content: { ... },
+//   editor: { ... }
+// }
+```
+
+```javascript codeFormat="commonjs"
+const { getConfiguration } = require("intlayer");
+
+const config = getConfiguration();
+console.log(config);
+// 출력:
+// {
+//   internationalization: { ... },
+//   middleware: { ... },
+//   content: { ... },
+//   editor: { ... }
+// }
+```
+
+### `availableLocales` 및 `defaultLocale` 추출하기
+
+구성의 `internationalization` 섹션은 `locales`(사용 가능한 로케일) 및 `defaultLocale`(기본 언어)과 같은 로케일 관련 설정을 제공합니다.
+
+```typescript codeFormat="typescript"
+import { getConfiguration } from "intlayer";
+
+const { internationalization, middleware } = getConfiguration();
+const { locales: availableLocales, defaultLocale } = internationalization;
+const { cookieName } = middleware;
+
+console.log(availableLocales); // 출력 예: ["en", "fr", "es"]
+console.log(defaultLocale); // 출력 예: "en"
+console.log(cookieName); // 출력: "INTLAYER_LOCALE"
+```
+
+```javascript codeFormat="esm"
+import { getConfiguration } from "intlayer";
+
+const { internationalization, middleware } = getConfiguration();
+const { locales: availableLocales, defaultLocale } = internationalization;
+const { cookieName } = middleware;
+
+console.log(availableLocales); // 출력 예: ["en", "fr", "es"]
+console.log(defaultLocale); // 출력 예: "en"
+console.log(cookieName); // 출력: "INTLAYER_LOCALE"
+```
+
+```javascript codeFormat="commonjs"
+const { getConfiguration } = require("intlayer");
+
+const { internationalization, middleware } = getConfiguration();
+const { locales: availableLocales, defaultLocale } = internationalization;
+const { cookieName } = middleware;
+
+console.log(availableLocales); // 출력 예: ["en", "fr", "es"]
+console.log(defaultLocale); // 출력 예: "en"
+console.log(cookieName); // 출력: "INTLAYER_LOCALE"
+```
+
+## 참고 사항
+
+- 이 함수를 호출하기 전에 모든 필수 환경 변수가 올바르게 설정되었는지 확인하세요. 누락된 변수는 초기화 중 오류를 발생시킵니다.
+- 이 함수는 클라이언트와 서버 측에서 모두 사용할 수 있어 통합된 방식으로 구성을 관리하는 데 유용합니다.
+
+## 애플리케이션에서의 사용
+
+`getConfiguration` 함수는 `intlayer` 애플리케이션의 구성을 초기화하고 관리하기 위한 핵심 유틸리티입니다. 로케일, 미들웨어 및 콘텐츠 디렉토리와 같은 설정에 대한 액세스를 제공함으로써 다국어 및 콘텐츠 중심 애플리케이션 전반에 걸쳐 일관성과 확장성을 보장합니다.

package/ko/packages/intlayer/getEnumeration.md

@@ -0,0 +1,138 @@
+# 문서: `getEnumeration` 함수 in `intlayer`
+
+## 설명
+
+`getEnumeration` 함수는 열거 객체에서 사전 정의된 조건에 따라 특정 수량에 해당하는 콘텐츠를 검색합니다. 조건은 키로 정의되며, 객체 내 순서에 따라 우선순위가 결정됩니다.
+
+## 매개변수
+
+- `enumerationContent: QuantityContent<Content>`
+
+  - **설명**: 키가 조건(예: `<=`, `<`, `>=`, `=`)을 나타내고 값이 해당 콘텐츠를 나타내는 객체입니다. 키의 순서는 매칭 우선순위를 정의합니다.
+  - **유형**: `QuantityContent<Content>`
+    - `Content`는 모든 유형이 가능합니다.
+
+- `quantity: number`
+
+  - **설명**: `enumerationContent`의 조건과 매칭하기 위해 사용되는 숫자 값입니다.
+  - **유형**: `number`
+
+## 반환값
+
+- **유형**: `Content`
+- **설명**: `enumerationContent`에서 첫 번째로 매칭되는 조건에 해당하는 콘텐츠입니다. 매칭이 없을 경우, 구현에 따라 기본 처리(예: 오류 또는 대체 콘텐츠)가 이루어집니다.
+
+## 사용 예시
+
+### 기본 사용법
+
+```typescript codeFormat="typescript"
+import { getEnumeration } from "intlayer";
+
+const content = getEnumeration(
+  {
+    "<=-2.3": "You have less than -2.3", // -2.3보다 작거나 같은 경우
+    "<1": "You have less than one", // 1보다 작은 경우
+    "2": "You have two", // 2인 경우
+    ">=3": "You have three or more", // 3 이상인 경우
+  },
+  2
+);
+
+console.log(content); // 출력: "You have two"
+```
+
+```javascript codeFormat="esm"
+import { getEnumeration } from "intlayer";
+
+const content = getEnumeration(
+  {
+    "<1": "You have less than one", // 1보다 작은 경우
+    "2": "You have two", // 2인 경우
+    ">=3": "You have three or more", // 3 이상인 경우
+  },
+  2
+);
+
+console.log(content); // 출력: "You have two"
+```
+
+```javascript codeFormat="commonjs"
+const { getEnumeration } = require("intlayer");
+
+const content = getEnumeration(
+  {
+    "<1": "You have less than one", // 1보다 작은 경우
+    "2": "You have two", // 2인 경우
+    ">=3": "You have three or more", // 3 이상인 경우
+  },
+  2
+);
+
+console.log(content); // 출력: "You have two"
+```
+
+### 조건의 우선순위
+
+```typescript codeFormat="typescript"
+import { getEnumeration } from "intlayer";
+
+const content = getEnumeration(
+  {
+    "<4": "You have less than four", // 4보다 작은 경우
+    "2": "You have two", // 2인 경우
+  },
+  2
+);
+
+console.log(content); // 출력: "You have less than four"
+```
+
+```javascript codeFormat="esm"
+import { getEnumeration } from "intlayer";
+
+const content = getEnumeration(
+  {
+    "<4": "You have less than four", // 4보다 작은 경우
+    "2": "You have two", // 2인 경우
+  },
+  2
+);
+
+console.log(content); // 출력: "You have less than four"
+```
+
+```javascript codeFormat="commonjs"
+const { getEnumeration } = require("intlayer");
+
+const content = getEnumeration(
+  {
+    "<4": "You have less than four", // 4보다 작은 경우
+    "2": "You have two", // 2인 경우
+  },
+  2
+);
+
+console.log(content); // 출력: "You have less than four"
+```
+
+## 경계 사례
+
+- **매칭 조건 없음:**
+
+  - 제공된 수량과 매칭되는 조건이 없을 경우, 함수는 `undefined`를 반환하거나 명시적으로 기본/대체 시나리오를 처리합니다.
+
+- **모호한 조건:**
+
+  - 조건이 겹치는 경우, 객체 순서에 따라 첫 번째 매칭 조건이 우선합니다.
+
+- **잘못된 키:**
+
+  - 함수는 `enumerationContent`의 모든 키가 유효하고 조건으로 구문 분석 가능하다고 가정합니다. 잘못되거나 형식이 올바르지 않은 키는 예기치 않은 동작을 초래할 수 있습니다.
+
+- **TypeScript 강제:**
+  - 함수는 모든 키에서 `Content` 유형이 일관되도록 보장하여 검색된 콘텐츠의 타입 안전성을 제공합니다.
+
+## 참고
+
+- `findMatchingCondition` 유틸리티는 주어진 수량에 따라 적절한 조건을 결정하는 데 사용됩니다.

package/ko/packages/intlayer/getHTMLTextDir.md

@@ -0,0 +1,97 @@
+# Documentation: `getHTMLTextDir` 함수 in `intlayer`
+
+## 설명
+
+`getHTMLTextDir` 함수는 제공된 로케일에 따라 텍스트 방향(`ltr`, `rtl`, 또는 `auto`)을 결정합니다. 이 함수는 개발자가 HTML에서 텍스트 렌더링을 위해 `dir` 속성을 설정할 수 있도록 설계되었습니다.
+
+## 매개변수
+
+- `locale?: Locales`
+
+  - **설명**: 텍스트 방향을 결정하기 위해 사용되는 로케일 문자열 (예: `Locales.ENGLISH`, `Locales.ARABIC`).
+  - **유형**: `Locales` (선택 사항)
+
+## 반환값
+
+- **유형**: `Dir` (`'ltr' | 'rtl' | 'auto'`)
+- **설명**: 로케일에 해당하는 텍스트 방향:
+  - `'ltr'`: 왼쪽에서 오른쪽으로 쓰는 언어.
+  - `'rtl'`: 오른쪽에서 왼쪽으로 쓰는 언어.
+  - `'auto'`: 로케일이 인식되지 않을 경우.
+
+## 사용 예제
+
+### 텍스트 방향 결정
+
+```typescript codeFormat="typescript"
+import { getHTMLTextDir } from "intlayer";
+
+getHTMLTextDir(Locales.ENGLISH); // 출력: "ltr"
+getHTMLTextDir(Locales.FRENCH); // 출력: "ltr"
+getHTMLTextDir(Locales.ARABIC); // 출력: "rtl"
+```
+
+```javascript codeFormat="esm"
+import { getHTMLTextDir } from "intlayer";
+
+getHTMLTextDir(Locales.ENGLISH); // 출력: "ltr"
+getHTMLTextDir(Locales.FRENCH); // 출력: "ltr"
+getHTMLTextDir(Locales.ARABIC); // 출력: "rtl"
+```
+
+```javascript codeFormat="commonjs"
+const { getHTMLTextDir } = require("intlayer");
+
+getHTMLTextDir(Locales.ENGLISH); // 출력: "ltr"
+getHTMLTextDir(Locales.FRENCH); // 출력: "ltr"
+getHTMLTextDir(Locales.ARABIC); // 출력: "rtl"
+```
+
+## 엣지 케이스
+
+- **로케일이 제공되지 않은 경우:**
+
+  - `locale`이 `undefined`일 때 함수는 `'auto'`를 반환합니다.
+
+- **인식되지 않는 로케일:**
+  - 인식되지 않는 로케일의 경우 함수는 기본값으로 `'auto'`를 반환합니다.
+
+## 컴포넌트에서의 사용:
+
+`getHTMLTextDir` 함수는 로케일에 따라 HTML 문서에서 텍스트 렌더링을 위해 `dir` 속성을 동적으로 설정하는 데 사용할 수 있습니다.
+
+```tsx codeFormat="typescript"
+import type { FC } from "react";
+import { getHTMLTextDir, type Locales } from "intlayer";
+
+export const HTMLLayout: FC<PropsWithChildren<{ locale: Locales }>> = ({
+  children,
+  locale,
+}) => (
+  <html dir={getHTMLTextDir(locale)} locale={locale}>
+    <body>{children}</body>
+  </html>
+);
+```
+
+```jsx codeFormat="esm"
+import { getHTMLTextDir } from "intlayer";
+
+const HTMLLayout = ({ children, locale }) => (
+  <html dir={getHTMLTextDir(locale)} locale={locale}>
+    <body>{children}</body>
+  </html>
+);
+```
+
+```jsx codeFormat="commonjs"
+const { getHTMLTextDir } = require("intlayer");
+
+const HTMLLayout = ({ children, locale }) => (
+  <html dir={getHTMLTextDir(locale)} locale={locale}>
+    <body>{children}</body>
+  </html>
+);
+```
+
+위 예제에서 `dir` 속성은 로케일에 따라 동적으로 설정됩니다.

package/ko/packages/intlayer/getLocaleLang.md

@@ -0,0 +1,57 @@
+# 문서: `getLocaleLang` 함수 in `intlayer`
+
+## 설명
+
+`getLocaleLang` 함수는 로케일 문자열에서 언어 코드를 추출합니다. 국가 코드가 포함되거나 포함되지 않은 로케일을 지원합니다. 로케일이 제공되지 않으면 기본적으로 빈 문자열을 반환합니다.
+
+## 매개변수
+
+- `locale?: Locales`
+
+  - **설명**: 언어 코드를 추출할 로케일 문자열 (예: `Locales.ENGLISH_UNITED_STATES`, `Locales.FRENCH_CANADA`).
+  - **유형**: `Locales` (선택 사항)
+
+## 반환값
+
+- **유형**: `string`
+- **설명**: 로케일에서 추출된 언어 코드. 로케일이 제공되지 않으면 빈 문자열 (`''`)을 반환합니다.
+
+## 사용 예시
+
+### 언어 코드 추출:
+
+```typescript codeFormat="typescript"
+import { getLocaleLang, Locales } from "intlayer";
+
+getLocaleLang(Locales.ENGLISH_UNITED_STATES); // 출력: "en"
+getLocaleLang(Locales.ENGLISH); // 출력: "en"
+getLocaleLang(Locales.FRENCH_CANADA); // 출력: "fr"
+getLocaleLang(Locales.FRENCH); // 출력: "fr"
+```
+
+```javascript codeFormat="esm"
+import { getLocaleLang } from "intlayer";
+
+getLocaleLang(Locales.ENGLISH_UNITED_STATES); // 출력: "en"
+getLocaleLang(Locales.ENGLISH); // 출력: "en"
+getLocaleLang(Locales.FRENCH_CANADA); // 출력: "fr"
+getLocaleLang(Locales.FRENCH); // 출력: "fr"
+```
+
+```javascript codeFormat="commonjs"
+const { getLocaleLang } = require("intlayer");
+
+getLocaleLang(Locales.ENGLISH_UNITED_STATES); // 출력: "en"
+getLocaleLang(Locales.ENGLISH); // 출력: "en"
+getLocaleLang(Locales.FRENCH_CANADA); // 출력: "fr"
+getLocaleLang(Locales.FRENCH); // 출력: "fr"
+```
+
+## 경계 사례
+
+- **로케일이 제공되지 않은 경우:**
+
+  - `locale`이 `undefined`인 경우 함수는 빈 문자열을 반환합니다.
+
+- **잘못된 로케일 문자열:**
+  - `locale`이 `language-country` 형식을 따르지 않는 경우 (예: `Locales.ENGLISH-US`), 함수는 안전하게 `'-'` 이전 부분을 반환하거나 `'-'`가 없는 경우 전체 문자열을 반환합니다.

package/ko/packages/intlayer/getLocaleName.md

@@ -0,0 +1,93 @@
+# 문서: `getLocaleName` 함수 in `intlayer`
+
+## 설명
+
+`getLocaleName` 함수는 주어진 로케일(`targetLocale`)의 로컬라이즈된 이름을 표시 로케일(`displayLocale`)에서 반환합니다. `targetLocale`이 제공되지 않으면, 표시 로케일의 이름을 해당 언어로 반환합니다.
+
+## 매개변수
+
+- `displayLocale: Locales`
+
+  - **설명**: 대상 로케일의 이름이 표시될 로케일입니다.
+  - **유형**: 유효한 로케일을 나타내는 열거형 또는 문자열.
+
+- `targetLocale?: Locales`
+  - **설명**: 로컬라이즈된 이름을 가져올 로케일입니다.
+  - **유형**: 선택 사항. 유효한 로케일을 나타내는 열거형 또는 문자열.
+
+## 반환값
+
+- **유형**: `string`
+- **설명**: `displayLocale`에서 `targetLocale`의 로컬라이즈된 이름 또는 `targetLocale`이 제공되지 않은 경우 `displayLocale` 자신의 이름. 번역을 찾을 수 없는 경우 `"Unknown locale"`을 반환합니다.
+
+## 사용 예시
+
+```typescript codeFormat="typescript"
+import { Locales, getLocaleName } from "intlayer";
+
+getLocaleName(Locales.ENGLISH); // 출력: "English"
+getLocaleName(Locales.ENGLISH, Locales.FRENCH); // 출력: "Anglais"
+getLocaleName(Locales.ENGLISH, Locales.ESPANOL); // 출력: "Inglés"
+getLocaleName(Locales.ENGLISH, Locales.ENGLISH); // 출력: "English"
+
+getLocaleName(Locales.FRENCH); // 출력: "Français"
+getLocaleName(Locales.FRENCH, Locales.FRENCH); // 출력: "Français"
+getLocaleName(Locales.FRENCH, Locales.ESPANOL); // 출력: "Francés"
+getLocaleName(Locales.FRENCH, Locales.ENGLISH); // 출력: "French"
+
+getLocaleName(Locales.CHINESE); // 출력: "中文"
+getLocaleName(Locales.CHINESE, Locales.FRENCH); // 출력: "Chinois"
+getLocaleName(Locales.CHINESE, Locales.ESPANOL); // 출력: "Chino"
+getLocaleName(Locales.CHINESE, Locales.ENGLISH); // 출력: "Chinese"
+
+getLocaleName("unknown-locale"); // 출력: "Unknown locale"
+```
+
+```javascript codeFormat="esm"
+import { Locales, getLocaleName } from "intlayer";
+
+getLocaleName(Locales.ENGLISH); // 출력: "English"
+getLocaleName(Locales.ENGLISH, Locales.FRENCH); // 출력: "Anglais"
+getLocaleName(Locales.ENGLISH, Locales.ESPANOL); // 출력: "Inglés"
+getLocaleName(Locales.ENGLISH, Locales.ENGLISH); // 출력: "English"
+
+getLocaleName(Locales.FRENCH); // 출력: "Français"
+getLocaleName(Locales.FRENCH, Locales.FRENCH); // 출력: "Français"
+getLocaleName(Locales.FRENCH, Locales.ESPANOL); // 출력: "Francés"
+getLocaleName(Locales.FRENCH, Locales.ENGLISH); // 출력: "French"
+
+getLocaleName(Locales.CHINESE); // 출력: "中文"
+getLocaleName(Locales.CHINESE, Locales.FRENCH); // 출력: "Chinois"
+getLocaleName(Locales.CHINESE, Locales.ESPANOL); // 출력: "Chino"
+getLocaleName(Locales.CHINESE, Locales.ENGLISH); // 출력: "Chinese"
+
+getLocaleName("unknown-locale"); // 출력: "Unknown locale"
+```
+
+```javascript codeFormat="commonjs"
+const { Locales, getLocaleName } = require("intlayer");
+
+getLocaleName(Locales.ENGLISH); // 출력: "English"
+getLocaleName(Locales.ENGLISH, Locales.FRENCH); // 출력: "Anglais"
+getLocaleName(Locales.ENGLISH, Locales.ESPANOL); // 출력: "Inglés"
+getLocaleName(Locales.ENGLISH, Locales.ENGLISH); // 출력: "English"
+
+getLocaleName(Locales.FRENCH); // 출력: "Français"
+getLocaleName(Locales.FRENCH, Locales.FRENCH); // 출력: "Français"
+getLocaleName(Locales.FRENCH, Locales.ESPANOL); // 출력: "Francés"
+getLocaleName(Locales.FRENCH, Locales.ENGLISH); // 출력: "French"
+
+getLocaleName(Locales.CHINESE); // 출력: "中文"
+getLocaleName(Locales.CHINESE, Locales.FRENCH); // 출력: "Chinois"
+getLocaleName(Locales.CHINESE, Locales.ESPANOL); // 출력: "Chino"
+getLocaleName(Locales.CHINESE, Locales.ENGLISH); // 출력: "Chinese"
+
+getLocaleName("unknown-locale"); // 출력: "Unknown locale"
+```
+
+## 엣지 케이스
+
+- **`targetLocale`가 제공되지 않은 경우:**
+  - 함수는 기본적으로 `displayLocale` 자신의 이름을 반환합니다.
+- **번역 누락:**
+  - `localeNameTranslations`에 `targetLocale` 또는 특정 `displayLocale`에 대한 항목이 없으면, 함수는 `ownLocalesName`으로 대체하거나 `"Unknown locale"`을 반환합니다.