@intlayer/docs 8.0.4 → 8.0.5

package/docs/ko/intlayer_with_analog.md

@@ -0,0 +1,365 @@
+---
+createdAt: 2025-04-18
+updatedAt: 2025-12-30
+title: Analog i18n - Analog 앱 번역 방법 – 2026 가이드
+description: Analog 앱을 다국어로 만드는 방법을 알아보세요. 가이드를 따라 국제화(i18n) 및 번역을 적용하세요.
+keywords:
+  - 국제화
+  - 문서
+  - Intlayer
+  - Analog
+  - Angular
+  - JavaScript
+slugs:
+  - doc
+  - environment
+  - analog
+applicationTemplate: https://github.com/aymericzip/intlayer/tree/main/examples/analog-app-template
+history:
+  - version: 8.0.4
+    date: 2026-01-26
+    changes: 히스토리 초기화
+---
+
+# Intlayer를 사용하여 Analog (Angular) 앱 번역하기 | 국제화 (i18n)
+
+## 목차
+
+<TOC/>
+
+## Intlayer란 무엇인가요?
+
+**Intlayer**는 현대적인 웹 애플리케이션에서 다국어 지원을 단순화하기 위해 설계된 혁신적인 오픈 소스 국제화(i18n) 라이브러리입니다.
+
+Intlayer를 사용하면 다음을 할 수 있습니다:
+
+- **번역 관리 용이**: 컴포넌트 수준에서 선언적 딕셔너리를 사용합니다.
+- **메타데이터, 라우트, 콘텐츠의 동적 로컬라이제이션**.
+- **TypeScript 지원 보장**: 자동 생성된 타입을 통해 자동 완성 및 오류 감지 기능을 향상시킵니다.
+- **고급 기능 활용**: 동적 로케일 감지 및 전환 등.
+
+---
+
+## Analog 애플리케이션에 Intlayer를 설정하는 단계별 가이드
+
+<Tabs defaultTab="code">
+  <Tab label="코드" value="code">
+
+<iframe
+  src="https://stackblitz.com/github/aymericzip/intlayer/tree/main/examples/vite-analog-app?embed=1&ctl=1&file=intlayer.config.ts"
+  className="m-auto overflow-hidden rounded-lg border-0 max-md:size-full max-md:h-[700px] md:aspect-16/9 md:w-full"
+  title="Demo CodeSandbox - How to Internationalize your application using Intlayer"
+  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
+  loading="lazy"
+/>
+
+  </Tab>
+</Tabs>
+
+GitHub에서 [애플리케이션 템플릿](https://github.com/aymericzip/intlayer/tree/main/examples/analog-app-template)을 확인하세요.
+
+### 1단계: 종속성 설치
+
+npm을 사용하여 필요한 패키지를 설치합니다:
+
+```bash packageManager="npm"
+npm install intlayer angular-intlayer vite-intlayer
+npx intlayer init
+```
+
+```bash packageManager="pnpm"
+pnpm add intlayer angular-intlayer vite-intlayer
+pnpm intlayer init
+```
+
+```bash packageManager="yarn"
+yarn add intlayer angular-intlayer vite-intlayer
+yarn intlayer init
+```
+
+```bash packageManager="bun"
+bun add intlayer angular-intlayer vite-intlayer
+bunx intlayer init
+```
+
+- **intlayer**
+
+  설정 관리, 번역, [콘텐츠 선언](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/content_file.md), 트랜스파일 및 [CLI 명령](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/cli/index.md)을 위한 국제화 도구를 제공하는 핵심 패키지입니다.
+
+- **angular-intlayer**
+  Intlayer를 Angular 애플리케이션과 통합하는 패키지입니다. Angular 국제화를 위한 컨텍스트 프로바이더와 훅을 제공합니다.
+
+- **vite-intlayer**
+  Intlayer를 Vite와 통합하는 패키지입니다. 콘텐츠 선언 파일을 처리하는 플러그인을 제공하고 최적의 성능을 위한 별칭(alias)을 설정합니다.
+
+### 2단계: 프로젝트 설정
+
+애플리케이션의 언어를 설정하기 위한 설정 파일을 생성합니다:
+
+```typescript fileName="intlayer.config.ts" codeFormat="typescript"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.SPANISH,
+      // 기타 로케일
+    ],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.mjs" codeFormat="esm"
+import { Locales } from "intlayer";
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  internationalization: {
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.SPANISH,
+      // 기타 로케일
+    ],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.cjs" codeFormat="commonjs"
+const { Locales } = require("intlayer");
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  internationalization: {
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.SPANISH,
+      // 기타 로케일
+    ],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+module.exports = config;
+```
+
+> 이 설정 파일을 통해 로컬라이즈된 URL, 미들웨어 리다이렉션, 쿠키 이름, 콘텐츠 선언의 위치 및 확장자 설정, 콘솔 내 Intlayer 로그 비활성화 등을 설정할 수 있습니다. 사용 가능한 전체 매개변수 목록은 [설정 문서](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md)를 참조하세요.
+
+### 3단계: Vite 설정에 Intlayer 통합
+
+Analog와 Intlayer를 통합하려면 `vite-intlayer` 플러그인을 사용해야 합니다.
+
+`vite.config.ts` 파일을 수정합니다:
+
+```typescript fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+import analog from "@analogjs/platform";
+
+// https://vitejs.dev/config/
+export default defineConfig(() => ({
+  plugins: [
+    analog(),
+    intlayer(), // Intlayer 플러그인 추가
+  ],
+}));
+```
+
+> `intlayer()` 플러그인은 Intlayer와 함께 Vite를 구성합니다. 콘텐츠 선언 파일을 처리하고 최적의 성능을 위한 별칭을 설정합니다.
+
+### 4단계: 콘텐츠 선언
+
+번역을 저장하기 위해 콘텐츠 선언을 생성하고 관리합니다:
+
+```tsx fileName="src/app/app.content.ts" contentDeclarationFormat="typescript"
+import { t, type Dictionary } from "intlayer";
+
+const appContent = {
+  key: "app",
+  content: {
+    title: t({
+      en: "Hello",
+      fr: "Bonjour",
+      es: "Hola",
+      ko: "안녕하세요",
+    }),
+    congratulations: t({
+      en: "Congratulations! Your app is running. 🎉",
+      fr: "Félicitations! Votre application est en cours d'exécution. 🎉",
+      es: "¡Felicidades! Tu aplicación está en ejecución. 🎉",
+      ko: "축하합니다! 앱이 실행 중입니다. 🎉",
+    }),
+  },
+} satisfies Dictionary;
+
+export default appContent;
+```
+
+> 콘텐츠 선언은 `contentDir` 디렉토리(기본값 `./src`)에 포함되어 있고 콘텐츠 선언 파일 확장자(기본값 `.content.{json,ts,tsx,js,jsx,mjs,cjs}`)와 일치하는 한 애플리케이션 어디에서나 정의할 수 있습니다.
+
+> 자세한 내용은 [콘텐츠 선언 문서](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/content_file.md)를 참조하세요.
+
+### 5단계: 코드에서 Intlayer 활용
+
+Analog 애플리케이션 전체에서 Intlayer의 국제화 기능을 활용하려면 애플리케이션 구성에서 Intlayer를 제공해야 합니다.
+
+```typescript fileName="src/app/app.config.ts"
+import { ApplicationConfig } from "@angular/core";
+import { provideIntlayer } from "angular-intlayer";
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideIntlayer(), // 여기에 Intlayer 프로바이더 추가
+  ],
+};
+```
+
+그런 다음 모든 컴포넌트 내에서 `useIntlayer` 함수를 사용할 수 있습니다.
+
+```typescript fileName="src/app/pages/index.page.ts"
+import { Component } from "@angular/core";
+import { useIntlayer } from "angular-intlayer";
+
+@Component({
+  selector: "app-home",
+  standalone: true,
+  template: `
+    <div class="content">
+      <h1>{{ content().title }}</h1>
+      <p>{{ content().congratulations }}</p>
+    </div>
+  `,
+})
+export default class HomeComponent {
+  content = useIntlayer("app");
+}
+```
+
+Intlayer 콘텐츠는 `Signal`로 반환되므로 시그널을 호출하여 값에 액세스합니다: `content().title`.
+
+### (선택 사항) 6단계: 콘텐츠 언어 변경
+
+콘텐츠 언어를 변경하려면 `useLocale` 함수에서 제공하는 `setLocale` 함수를 사용할 수 있습니다. 이를 통해 애플리케이션의 로케일을 설정하고 그에 따라 콘텐츠를 업데이트할 수 있습니다.
+
+언어를 전환하기 위한 컴포넌트를 생성합니다:
+
+```typescript fileName="src/app/locale-switcher.component.ts"
+import { Component } from "@angular/core";
+import { CommonModule } from "@angular/common";
+import { useLocale } from "angular-intlayer";
+
+@Component({
+  selector: "app-locale-switcher",
+  standalone: true,
+  imports: [CommonModule],
+  template: `
+    <div class="locale-switcher">
+      <select
+        [value]="locale()"
+        (change)="setLocale($any($event.target).value)"
+      >
+        @for (loc of availableLocales; track loc) {
+          <option [value]="loc">{{ loc }}</option>
+        }
+      </select>
+    </div>
+  `,
+  styles: [
+    `
+      .locale-switcher {
+        margin: 1rem;
+        padding: 0.5rem;
+        border: 1px solid #ccc;
+        border-radius: 4px;
+        width: fit-content;
+      }
+    `,
+  ],
+})
+export class LocaleSwitcherComponent {
+  localeCtx = useLocale();
+
+  locale = this.localeCtx.locale;
+  availableLocales = this.localeCtx.availableLocales;
+  setLocale = this.localeCtx.setLocale;
+}
+```
+
+그런 다음 페이지에서 이 컴포넌트를 사용합니다:
+
+```typescript fileName="src/app/pages/index.page.ts"
+import { Component } from "@angular/core";
+import { useIntlayer } from "angular-intlayer";
+import { LocaleSwitcherComponent } from "../locale-switcher.component";
+
+@Component({
+  selector: "app-home",
+  standalone: true,
+  imports: [LocaleSwitcherComponent],
+  template: `
+    <app-locale-switcher></app-locale-switcher>
+    <div class="content">
+      <h1>{{ content().title }}</h1>
+      <p>{{ content().congratulations }}</p>
+    </div>
+  `,
+})
+export default class HomeComponent {
+  content = useIntlayer("app");
+}
+```
+
+### TypeScript 설정
+
+Intlayer는 모듈 보강(module augmentation)을 사용하여 TypeScript의 이점을 활용하고 코드베이스를 더욱 강력하게 만듭니다.
+
+![Autocompletion](https://github.com/aymericzip/intlayer/blob/main/docs/assets/autocompletion.png?raw=true)
+
+![Translation error](https://github.com/aymericzip/intlayer/blob/main/docs/assets/translation_error.png?raw=true)
+
+TypeScript 구성에 자동 생성된 타입이 포함되어 있는지 확인하세요.
+
+```json5 fileName="tsconfig.json"
+{
+  // ... 기존 TypeScript 구성
+  "include": [
+    // ... 기존 TypeScript 구성
+    ".intlayer/**/*.ts", // 자동 생성된 타입 포함
+  ],
+}
+```
+
+### Git 설정
+
+Intlayer에서 생성된 파일은 무시하는 것이 좋습니다. 이렇게 하면 Git 저장소에 커밋하는 것을 피할 수 있습니다.
+
+이를 위해 `.gitignore` 파일에 다음 지침을 추가할 수 있습니다:
+
+```plaintext
+# Intlayer에서 생성된 파일 무시
+.intlayer
+```
+
+### VS Code 확장 프로그램
+
+Intlayer 개발 환경을 개선하려면 공식 **Intlayer VS Code Extension**을 설치할 수 있습니다.
+
+[VS Code Marketplace에서 설치](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)
+
+이 확장 프로그램은 다음을 제공합니다:
+
+- 번역 키에 대한 **자동 완성**.
+- 누락된 번역에 대한 **실시간 오류 감지**.
+- 번역된 콘텐츠의 **인라인 미리보기**.
+- 번역을 쉽게 생성하고 업데이트할 수 있는 **빠른 작업**.
+
+확장 프로그램 사용 방법에 대한 자세한 내용은 [Intlayer VS Code Extension 문서](https://intlayer.org/doc/vs-code-extension)를 참조하세요.

package/docs/ko/intlayer_with_angular.md

@@ -166,30 +166,28 @@ Intlayer를 Angular CLI와 통합하려면 사용자 정의 빌더를 사용해
 
 먼저, `angular.json`을 수정하여 사용자 정의 Webpack 빌더를 사용하도록 합니다. `build` 및 `serve` 구성을 업데이트하세요:
 
-```json fileName="angular.json"
+```json5 fileName="angular.json"
 {
   "projects": {
     "your-app-name": {
       "architect": {
         "build": {
-          "builder": "@angular-builders/custom-webpack:browser",
+          "builder": "@angular-builders/custom-webpack:browser", // replace "@angular-devkit/build-angular:application",
           "options": {
             "customWebpackConfig": {
-              "path": "./webpack.config.ts"
-            }
-          }
+              "path": "./webpack.config.ts",
+              "mergeStrategies": { "module.rules": "prepend" },
+            },
+            "main": "src/main.ts", // replace "browser": "src/main.ts",
+            // ...
+          },
         },
         "serve": {
           "builder": "@angular-builders/custom-webpack:dev-server",
-          "options": {
-            "customWebpackConfig": {
-              "path": "./webpack.config.ts"
-            }
-          }
-        }
-      }
-    }
-  }
+        },
+      },
+    },
+  },
 }
 ```
 

package/docs/ko/packages/solid-intlayer/useIntlayer.md

@@ -33,7 +33,7 @@ history:
 import { useIntlayer } from "solid-intlayer";
 
 const MyComponent = () => {
-  const content = useIntlayer("my_dictionary_key");
+  const content = useIntlayer("my-dictionary-key");
 
   return (
     <div>

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

@@ -86,6 +86,7 @@ npx intlayer doc translate
 - **`--temperature [temperature]`**: Ustawienie temperatury dla modelu AI.
 - **`--api-key [apiKey]`**: Podaj własny klucz API dla usługi AI.
 - **`--application-context [applicationContext]`**: Podaj dodatkowy kontekst dla tłumaczenia AI.
+- **`--data-serialization [dataSerialization]`**: Format serializacji danych dla funkcji AI w Intlayer. Opcje: `json` (standardowy, niezawodny), `toon` (mniej tokenów, mniej spójny).
 - **`--custom-prompt [prompt]`**: Dostosuj podstawowy prompt używany do tłumaczenia. (Uwaga: W większości przypadków zaleca się użycie opcji `--custom-instructions`, ponieważ zapewnia lepszą kontrolę nad zachowaniem tłumaczenia.)
 
   > Przykład: `npx intlayer doc translate --model deepseek-chat --provider deepseek --temperature 0.5 --api-key sk-1234567890 --application-context "Moja aplikacja to sklep z kotami"`

package/docs/pl/cli/fill.md

@@ -126,6 +126,7 @@ Affected dictionary keys for processing: app, comp-test, hello-world, lang-switc
 - **`--api-key [apiKey]`**: Podaj własny klucz API dla usługi AI.
 - **`--custom-prompt [prompt]`**: Podaj niestandardowe polecenie dla instrukcji tłumaczenia.
 - **`--application-context [applicationContext]`**: Podaj dodatkowy kontekst dla tłumaczenia AI.
+- **`--data-serialization [dataSerialization]`**: Format serializacji danych dla funkcji AI w Intlayer. Opcje: `json` (standardowy, niezawodny), `toon` (mniej tokenów, mniej spójny).
 
   > Przykład: `npx intlayer fill --model gpt-3.5-turbo --provider openai --temperature 0.5 --api-key sk-1234567890 --application-context "Moja aplikacja to sklep z kotami"`
 

package/docs/pl/configuration.md

@@ -14,6 +14,9 @@ slugs:
   - concept
   - configuration
 history:
+  - version: 8.0.5
+    date: 2026-02-06
+    changes: Dodano `dataSerialization` do konfiguracji AI
   - version: 8.0.0
     date: 2026-01-22
     changes: Move `importMode` build configuration to `dictionary` configuration.
@@ -987,6 +990,13 @@ Intlayer obsługuje wielu dostawców AI, aby zapewnić większą elastyczność
   - _Przykład_: `'https://api.openai.com/v1'`
   - _Uwaga_: Może być używany do wskazania lokalnego lub niestandardowego punktu końcowego API AI.
 
+- **dataSerialization**:
+  - _Typ_: `'json' | 'toon'`
+  - _Domyślnie_: `'json'`
+  - _Opis_: Format serializacji danych dla funkcji AI w Intlayer.
+  - _Przykład_: `'toon'`
+  - _Uwaga_: `json`: Standardowy, niezawodny; zużywa więcej tokenów. `toon`: Mniej tokenów, mniej spójny niż JSON.
+
 ### Konfiguracja Budowania
 
 Ustawienia kontrolujące, jak Intlayer optymalizuje i buduje internacjonalizację Twojej aplikacji.