@intlayer/docs 5.7.2-canary.3 → 5.7.3

package/docs/ko/dictionary/gender.md

@@ -0,0 +1,275 @@
+---
+createdAt: 2025-07-27
+updatedAt: 2025-07-27
+title: 성별 기반 콘텐츠
+description: Intlayer에서 성별 기반 콘텐츠를 사용하여 성별에 따라 동적으로 콘텐츠를 표시하는 방법을 알아보세요. 이 문서를 따라 프로젝트에서 성별별 콘텐츠를 효율적으로 구현할 수 있습니다.
+keywords:
+  - 성별 기반 콘텐츠
+  - 동적 렌더링
+  - 문서
+  - Intlayer
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - concept
+  - content
+  - gender
+---
+
+# 성별 기반 콘텐츠 / Intlayer의 성별
+
+## 성별 작동 방식
+
+Intlayer에서는 `gender` 함수를 통해 성별 기반 콘텐츠를 구현합니다. 이 함수는 특정 성별 값('male', 'female')을 해당하는 콘텐츠에 매핑합니다. 이 방식을 통해 주어진 성별에 따라 동적으로 콘텐츠를 선택할 수 있습니다. React Intlayer 또는 Next Intlayer와 통합하면, 런타임에 제공된 성별에 따라 적절한 콘텐츠가 자동으로 선택됩니다.
+
+## 성별 기반 콘텐츠 설정
+
+Intlayer 프로젝트에서 성별 기반 콘텐츠를 설정하려면, 성별별 정의를 포함하는 콘텐츠 모듈을 생성하세요. 아래는 다양한 형식의 예시입니다.
+
+```typescript fileName="**/*.content.ts" contentDeclarationFormat="typescript"
+import { gender, type Dictionary } from "intlayer";
+
+const myGenderContent = {
+  key: "my_key",
+  content: {
+    myGender: gender({
+      male: "남성 사용자용 콘텐츠",
+      female: "여성 사용자용 콘텐츠",
+      fallback: "성별이 지정되지 않았을 때의 콘텐츠", // 선택 사항
+    }),
+  },
+} satisfies Dictionary;
+
+export default myGenderContent;
+```
+
+```javascript fileName="**/*.content.mjs" contentDeclarationFormat="esm"
+import { gender } from "intlayer";
+
+/** @type {import('intlayer').Dictionary} */
+const myGenderContent = {
+  key: "my_key",
+  content: {
+    myGender: gender({
+      male: "남성 사용자용 콘텐츠",
+      female: "여성 사용자용 콘텐츠",
+      fallback: "성별이 지정되지 않았을 때의 콘텐츠", // 선택 사항
+    }),
+  },
+};
+
+export default myGenderContent;
+```
+
+```javascript fileName="**/*.content.cjs" contentDeclarationFormat="commonjs"
+const { gender } = require("intlayer");
+
+/** @type {import('intlayer').Dictionary} */
+const myGenderContent = {
+  key: "my_key",
+  content: {
+    myGender: gender({
+      male: "남성 사용자용 콘텐츠",
+      female: "여성 사용자용 콘텐츠",
+      fallback: "성별이 지정되지 않았을 때의 콘텐츠", // 선택 사항
+    }),
+  },
+};
+
+module.exports = myGenderContent;
+```
+
+```json5 fileName="**/*.content.json" contentDeclarationFormat="json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "my_key",
+  "content": {
+    "myGender": {
+      "nodeType": "gender",
+      "gender": {
+        "male": "남성 사용자용 콘텐츠",
+        "female": "여성 사용자용 콘텐츠",
+        "fallback": "성별이 지정되지 않았을 때의 콘텐츠", // 선택 사항
+      },
+    },
+  },
+}
+```
+
+> 만약 fallback이 선언되지 않았다면, 성별이 지정되지 않았거나 정의된 성별과 일치하지 않을 경우 마지막으로 선언된 키가 fallback으로 사용됩니다.
+
+## React Intlayer에서 성별 기반 콘텐츠 사용하기
+
+React 컴포넌트 내에서 성별 기반 콘텐츠를 활용하려면, `react-intlayer` 패키지에서 `useIntlayer` 훅을 임포트하여 사용하세요. 이 훅은 지정된 키에 대한 콘텐츠를 가져오며, 적절한 출력을 선택하기 위해 성별을 전달할 수 있습니다.
+
+```tsx fileName="**/*.tsx" codeFormat="typescript"
+import type { FC } from "react";
+import { useIntlayer } from "react-intlayer";
+
+const GenderComponent: FC = () => {
+  const { myGender } = useIntlayer("my_key");
+
+  return (
+    <div>
+      <p>
+        {
+          /* 출력: 남성 사용자용 콘텐츠 */
+          myGender("male")
+        }
+      </p>
+      <p>
+        {
+          /* 출력: 여성 사용자용 내 콘텐츠 */
+          myGender("female")
+        }
+      </p>
+      <p>
+        {
+          /* 출력: 남성 사용자용 내 콘텐츠 */
+          myGender("m")
+        }
+      </p>
+      <p>
+        {
+          /* 출력: 여성 사용자용 내 콘텐츠 */
+          myGender("f")
+        }
+      </p>
+      <p>
+        {
+          /* 출력: 성별이 지정되지 않았을 때 내 콘텐츠 */
+          myGender("")
+        }
+      </p>
+      <p>
+        {
+          /* 출력: 성별이 지정되지 않았을 때 내 콘텐츠 */
+          myGender(undefined)
+        }
+      </p>
+    </div>
+  );
+};
+
+export default GenderComponent;
+```
+
+```javascript fileName="**/*.mjx" codeFormat="esm"
+import { useIntlayer } from "react-intlayer";
+
+const GenderComponent = () => {
+  const { myGender } = useIntlayer("my_key");
+
+  return (
+    <div>
+      <p>
+        {
+          /* 출력: 남성 사용자용 내 콘텐츠 */
+          myGender("male")
+        }
+      </p>
+      <p>
+        {
+          /* 출력: 여성 사용자용 내 콘텐츠 */
+          myGender("female")
+        }
+      </p>
+      <p>
+        {
+          /* 출력: 남성 사용자용 내 콘텐츠 */
+          myGender("m")
+        }
+      </p>
+      <p>
+        {
+          /* 출력: 여성 사용자용 내 콘텐츠 */
+          myGender("f")
+        }
+      </p>
+      <p>
+        {
+          /* 출력: 성별이 지정되지 않았을 때 내 콘텐츠 */
+          myGender("")
+        }
+      </p>
+      <p>
+        {
+          /* 출력: 성별이 지정되지 않았을 때 내 콘텐츠 */
+          myGender(undefined)
+        }
+      </p>
+    </div>
+  );
+};
+
+export default GenderComponent;
+```
+
+```javascript fileName="**/*.cjs" codeFormat="commonjs"
+const { useIntlayer } = require("react-intlayer");
+
+const GenderComponent = () => {
+  const { myGender } = useIntlayer("my_key");
+
+  return (
+    <div>
+      <p>
+        {
+          /* 출력: 남성 사용자용 콘텐츠 */
+          myGender("male")
+        }
+      </p>
+      <p>
+        {
+          /* 출력: 여성 사용자용 콘텐츠 */
+          myGender("female")
+        }
+      </p>
+      <p>
+        {
+          /* 출력: 남성 사용자용 콘텐츠 */
+          myGender("m")
+        }
+      </p>
+      <p>
+        {
+          /* 출력: 여성 사용자용 콘텐츠 */
+          myGender("f")
+        }
+      </p>
+      <p>
+        {
+          /* 출력: 성별이 지정되지 않았을 때의 내 콘텐츠 */
+          myGender("")
+        }
+      </p>
+      <p>
+        {
+          /* 출력: 성별이 지정되지 않았을 때의 내 콘텐츠 */
+          myGender(undefined)
+        }
+      </p>
+    </div>
+  );
+};
+
+module.exports = GenderComponent;
+```
+
+## 추가 자료
+
+설정 및 사용법에 대한 자세한 정보는 다음 자료를 참조하세요:
+
+- [Intlayer CLI 문서](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/intlayer_cli.md)
+- [React Intlayer 문서](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/intlayer_with_create_react_app.md)
+- [Next Intlayer 문서](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/intlayer_with_nextjs_15.md)
+
+이 자료들은 다양한 환경과 프레임워크에서 Intlayer의 설정 및 사용에 대한 추가적인 통찰을 제공합니다.
+
+## 문서 이력
+
+| 버전  | 날짜       | 변경 사항             |
+| ----- | ---------- | --------------------- |
+| 5.7.2 | 2025-07-27 | 성별 기반 콘텐츠 도입 |

package/docs/ko/how_works_intlayer.md

@@ -93,7 +93,7 @@ Intlayer는 콘텐츠를 시각적으로 편집할 수 있는 시각적 편집
 
 - 서버는 클라이언트의 요청을 수신하고 애플리케이션의 `dictionaries`와 같은 콘텐츠 및 구성을 가져와 클라이언트 측에서 접근할 수 있도록 하는 간단한 Express 애플리케이션입니다.
 - 반면 클라이언트는 시각적 인터페이스를 사용하여 콘텐츠와 상호작용하는 데 사용되는 React 애플리케이션입니다.
-  `useIntlayer`를 사용하여 콘텐츠를 호출하고 편집기가 활성화되면, 자동으로 문자열을 `IntlayerNode`라는 Proxy 객체로 감쌉니다. 이 노드는 `window.sendMessage`를 사용하여 시각적 편집기 인터페이스가 포함된 래핑된 iframe과 통신합니다.  
+  `useIntlayer`를 사용하여 콘텐츠를 호출하고 편집기가 활성화되면, 자동으로 문자열을 `IntlayerNode`라는 Proxy 객체로 감쌉니다. 이 노드는 `window.postMessage`를 사용하여 시각적 편집기 인터페이스가 포함된 래핑된 iframe과 통신합니다.  
   편집기 측에서는 이러한 메시지를 수신하여 실제 콘텐츠와 상호작용하는 것처럼 시뮬레이션하며, 애플리케이션 컨텍스트 내에서 직접 텍스트를 편집할 수 있도록 합니다.
 
 ## 애플리케이션 빌드 최적화

package/docs/ko/locale_mapper.md

@@ -0,0 +1,244 @@
+---
+createdAt: 2025-07-27
+updatedAt: 2025-07-27
+title: 로케일 매퍼
+description: 로케일 매퍼가 어떻게 작동하는지 알아보세요. 애플리케이션에서 로케일 매퍼가 사용하는 단계를 확인하세요. 다양한 패키지가 하는 역할을 확인하세요.
+keywords:
+  - 로케일 매퍼
+  - 시작하기
+  - Intlayer
+  - 애플리케이션
+  - 패키지
+slugs:
+  - doc
+  - locale-mapper
+---
+
+# 로케일 매퍼
+
+로케일 매퍼는 Intlayer 애플리케이션에서 국제화 데이터를 다루는 데 도움을 주는 강력한 유틸리티입니다. 로케일별 데이터를 변환하고 조직하는 세 가지 주요 함수인 `localeMap`, `localeFlatMap`, `localeRecord`를 제공합니다.
+
+## 로케일 매퍼 작동 방식
+
+로케일 매퍼는 로케일에 관한 모든 필요한 정보를 포함하는 `LocaleData` 객체를 기반으로 작동합니다:
+
+```typescript
+type LocaleData = {
+  locale: LocalesValues; // 현재 로케일 코드 (예: 'en', 'fr')
+  defaultLocale: LocalesValues; // 기본 로케일 코드
+  isDefault: boolean; // 이 로케일이 기본 로케일인지 여부
+  locales: LocalesValues[]; // 사용 가능한 모든 로케일 배열
+  urlPrefix: string; // 이 로케일의 URL 접두사 (예: '/fr' 또는 '')
+};
+```
+
+매퍼 함수는 구성에 있는 각 로케일에 대해 이 데이터를 자동으로 생성하며, 다음 사항을 고려합니다:
+
+- 구성된 로케일 목록
+- 기본 로케일 설정
+- 기본 로케일이 URL에 접두사로 붙어야 하는지 여부
+
+## 핵심 함수
+
+### `localeMap`
+
+매퍼 함수를 사용하여 각 로케일을 단일 객체로 변환합니다.
+
+```typescript
+localeMap<T>(
+  mapper: (locale: LocaleData) => T,
+  locales?: LocalesValues[],
+  defaultLocale?: LocalesValues,
+  prefixDefault?: boolean
+): T[]
+```
+
+**예제: 라우트 객체 생성하기**
+
+```typescript
+import { localeMap } from "intlayer";
+
+const routes = localeMap((localizedData) => ({
+  path: localizedData.urlPrefix,
+  name: localizedData.locale,
+  isDefault: localizedData.isDefault,
+  locales: localizedData.locales,
+  defaultLocale: localizedData.defaultLocale,
+}));
+
+// 결과:
+// [
+//   { path: '/', name: 'en', isDefault: true, locales: ['en', 'fr', 'es'], defaultLocale: 'en' },
+//   { path: '/fr', name: 'fr', isDefault: false, locales: ['en', 'fr', 'es'], defaultLocale: 'en' },
+//   { path: '/es', name: 'es', isDefault: false, locales: ['en', 'fr', 'es'], defaultLocale: 'en' }
+// ]
+```
+
+### `localeFlatMap`
+
+`localeMap`과 유사하지만, 매퍼 함수가 객체 배열을 반환하며 이 배열이 단일 배열로 평탄화됩니다.
+
+```typescript
+localeFlatMap<T>(
+  mapper: (locale: LocaleData) => T[],
+  locales?: LocalesValues[],
+  defaultLocale?: LocalesValues,
+  prefixDefault?: boolean
+): T[]
+```
+
+**예제: 로케일별로 여러 경로 생성하기**
+
+```typescript
+import { localeFlatMap } from "intlayer";
+
+const routes = localeFlatMap((localizedData) => [
+  {
+    path: localizedData.urlPrefix,
+    name: localizedData.locale,
+    isDefault: localizedData.isDefault,
+  },
+  {
+    path: `${localizedData.urlPrefix}/about`,
+    name: `${localizedData.locale}-about`,
+    isDefault: localizedData.isDefault,
+  },
+]);
+
+// 결과:
+// [
+//   { path: '/', name: 'en', isDefault: true },
+  { path: '/about', name: 'en-about', isDefault: true },
+  { path: '/fr', name: 'fr', isDefault: false },
+  { path: '/fr/about', name: 'fr-about', isDefault: false },
+  { path: '/es', name: 'es', isDefault: false },
+  { path: '/es/about', name: 'es-about', isDefault: false }
+]
+```
+
+### `localeRecord`
+
+각 로케일이 키가 되고, 매퍼 함수에 의해 변환된 값을 매핑하는 레코드 객체를 생성합니다.
+
+```typescript
+localeRecord<T>(
+  mapper: (locale: LocaleData) => T,
+  locales?: Locales[],
+  defaultLocale?: Locales,
+  prefixDefault?: boolean
+): Record<Locales, T>
+```
+
+**예제: 번역 파일 로딩하기**
+
+```typescript
+import { localeRecord } from "intlayer";
+
+const translations = localeRecord(({ locale }) =>
+  require(`./translations/${locale}.json`)
+);
+
+// 결과:
+// {
+//   en: { welcome: 'Welcome', hello: 'Hello' },
+//   fr: { welcome: 'Bienvenue', hello: 'Bonjour' },
+//   es: { welcome: 'Bienvenido', hello: 'Hola' }
+// }
+```
+
+## 로케일 매퍼 설정하기
+
+로케일 매퍼는 자동으로 Intlayer 설정을 사용하지만, 매개변수를 전달하여 기본값을 재정의할 수 있습니다:
+
+### 기본 설정 사용하기
+
+```typescript
+import { localeMap } from "intlayer";
+
+// intlayer.config.ts의 설정을 사용합니다
+const routes = localeMap((data) => ({
+  path: data.urlPrefix,
+  locale: data.locale,
+}));
+```
+
+### 설정 재정의하기
+
+```typescript
+import { localeMap } from "intlayer";
+
+// 로케일과 기본 로케일을 재정의합니다
+const customRoutes = localeMap(
+  (data) => ({ path: data.urlPrefix, locale: data.locale }),
+  ["en", "fr", "de"], // 사용자 지정 로케일
+  "en", // 사용자 지정 기본 로케일
+  true // URL에 기본 로케일 접두사 추가
+);
+```
+
+## 고급 사용 예제
+
+### 내비게이션 메뉴 생성
+
+```typescript
+import { localeMap } from "intlayer";
+
+const navigationItems = localeMap((data) => ({
+  label: data.locale.toUpperCase(), // 로케일을 대문자로 표시
+  href: data.urlPrefix || "/", // URL 접두사 또는 기본 경로
+  isActive: data.isDefault, // 기본 로케일 여부
+  flag: `/flags/${data.locale}.svg`, // 로케일에 해당하는 국기 아이콘 경로
+}));
+```
+
+### 사이트맵 데이터 생성
+
+```typescript
+import { localeFlatMap } from "intlayer";
+
+const sitemapUrls = localeFlatMap((data) => [
+  {
+    url: `${data.urlPrefix}/`, // URL 경로
+    lastmod: new Date().toISOString(), // 마지막 수정 날짜
+    changefreq: "daily", // 변경 빈도
+    priority: data.isDefault ? 1.0 : 0.8, // 우선순위
+  },
+  {
+    url: `${data.urlPrefix}/about`,
+    lastmod: new Date().toISOString(),
+    changefreq: "monthly",
+    priority: data.isDefault ? 0.8 : 0.6,
+  },
+]);
+```
+
+### 동적 번역 로딩
+
+```typescript
+import { localeRecord } from "intlayer";
+
+const translationModules = localeRecord(({ locale }) => ({
+  messages: import(`./locales/${locale}/messages.json`),
+  validation: import(`./locales/${locale}/validation.json`),
+  metadata: {
+    locale,
+    direction: ["ar", "he", "fa"].includes(locale) ? "rtl" : "ltr", // 오른쪽에서 왼쪽으로 읽는 언어인지 여부
+  },
+}));
+```
+
+## 구성 통합
+
+Locale Mapper는 Intlayer 구성과 원활하게 통합됩니다:
+
+- **Locales**: `configuration.internationalization.locales`를 자동으로 사용합니다
+- **기본 로케일**: `configuration.internationalization.defaultLocale`를 사용합니다
+- **URL 접두사**: `configuration.middleware.prefixDefault`를 준수합니다
+
+이것은 애플리케이션 전반에 걸쳐 일관성을 보장하고 구성 중복을 줄여줍니다.
+
+## 문서 이력
+
+| 버전  | 날짜       | 변경 사항             |
+| ----- | ---------- | --------------------- |
+| 5.7.2 | 2025-07-27 | 로케일 매퍼 문서 추가 |