@intlayer/docs 8.0.4 → 8.0.5

package/docs/ja/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**は、現代的なWebアプリケーションにおける多言語サポートを簡素化するために設計された、革新的でオープンソースな国際化（i18n）ライブラリです。
+
+With Intlayer, you can:
+
+- **翻訳の簡単な管理**: コンポーネントレベルで宣言的な辞書を使用します。
+- **メタデータ、ルート、コンテンツの動的なローカライズ**。
+- **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と統合するパッケージ。コンテンツ宣言ファイルを処理するプラグインを提供し、最適なパフォーマンスのためのエイリアスを設定します。
+
+### ステップ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",
+      ja: "こんにちは",
+    }),
+    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. 🎉",
+      ja: "おめでとうございます！アプリが起動しました。 🎉",
+    }),
+  },
+} 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は、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/ja/intlayer_with_angular.md

@@ -166,30 +166,28 @@ IntlayerをAngular CLIと統合するには、カスタムビルダーを使用
 
 まず、カスタムWebpackビルダーを使用するように `angular.json` を変更します。`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/ja/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/ko/agent_skills.md

@@ -0,0 +1,53 @@
+---
+createdAt: 2026-02-09
+updatedAt: 2026-02-09
+title: 에이전트 스킬
+description: Intlayer 에이전트 스킬을 사용하여 AI 에이전트의 프로젝트 이해도를 높이는 방법을 배워보세요.
+keywords:
+  - Intlayer
+  - 에이전트 스킬
+  - AI 에이전트
+  - 국제화
+  - 문서
+slugs:
+  - doc
+  - agent_skills
+history:
+  - version: 8.0.4
+    date: 2026-02-09
+    changes: 내역 초기화
+---
+
+## `intlayer init skills` 명령어
+
+`intlayer init skills` 명령어는 프로젝트에 에이전트 스킬을 설정하는 가장 쉬운 방법입니다. 사용자 환경을 감지하고 선호하는 플랫폼에 필요한 구성 파일을 설치합니다.
+
+```bash
+npx intlayer init skills
+```
+
+이 명령어를 실행하면 다음과 같은 작업이 수행됩니다:
+
+1.  사용 중인 프레임워크(예: Next.js, React, Vite)를 감지합니다.
+2.  어떤 플랫폼(Cursor, VS Code, OpenCode, Claude Code 등)에 대한 스킬을 설치할지 묻습니다.
+3.  필요한 구성 파일(`.cursor/mcp.json`, `.vscode/mcp.json`, 또는 `.intlayer/skills/*.md` 등)을 생성합니다.
+
+## 지원되는 플랫폼
+
+Intlayer는 다음 플랫폼과의 통합을 지원합니다:
+
+### 1. Cursor
+
+Cursor는 MCP(Model Context Protocol) 서버를 지원합니다. `intlayer init skills`를 실행하면 Cursor가 Intlayer MCP 서버와 통신할 수 있도록 하는 `.cursor/mcp.json` 파일이 생성됩니다.
+
+### 2. VS Code
+
+VS Code 사용자, 특히 GitHub Copilot 또는 기타 MCP 호환 확장 프로그램을 사용하는 사용자를 위해 이 명령어는 `.vscode/mcp.json` 구성을 생성합니다.
+
+### 3. OpenCode
+
+OpenCode는 소프트웨어 엔지니어링 작업을 위해 설계된 대화형 CLI 에이전트입니다. Intlayer는 OpenCode가 국제화 작업을 지원할 수 있도록 특정 스킬을 제공합니다.
+
+### 4. Claude Code
+
+Claude Code는 생성된 구성을 데스크톱 또는 CLI 설정에 추가하여 Intlayer 스킬을 사용하도록 구성할 수 있습니다.

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

@@ -86,6 +86,7 @@ npx intlayer doc translate
 - **`--temperature [temperature]`**: AI 모델의 온도 설정.
 - **`--api-key [apiKey]`**: AI 서비스에 사용할 API 키를 제공합니다.
 - **`--application-context [applicationContext]`**: AI 번역에 추가 컨텍스트를 제공합니다.
+- **`--data-serialization [dataSerialization]`**: Intlayer의 AI 기능에 사용할 데이터 직렬화 형식. 옵션: `json` (표준, 신뢰할 수 있음), `toon` (토큰 적음, 일관성 낮음).
 - **`--custom-prompt [prompt]`**: 번역에 사용되는 기본 프롬프트를 사용자 정의합니다. (참고: 대부분의 사용 사례에서는 번역 동작을 더 잘 제어할 수 있는 `--custom-instructions` 옵션을 사용하는 것이 권장됩니다.)
 
   > 예시: `npx intlayer doc translate --model deepseek-chat --provider deepseek --temperature 0.5 --api-key sk-1234567890 --application-context "My application is a cat store"`

package/docs/ko/cli/fill.md

@@ -126,6 +126,7 @@ Affected dictionary keys for processing: app, comp-test, hello-world, lang-switc
 - **`--api-key [apiKey]`**: AI 서비스에 사용할 API 키 제공.
 - **`--custom-prompt [prompt]`**: 번역 지침을 위한 커스텀 프롬프트 제공.
 - **`--application-context [applicationContext]`**: AI 번역에 추가 컨텍스트 제공.
+- **`--data-serialization [dataSerialization]`**: Intlayer의 AI 기능에 사용할 데이터 직렬화 형식. 옵션: `json` (표준, 신뢰할 수 있음), `toon` (토큰 적음, 일관성 낮음).
 
   > 예시: `npx intlayer fill --model gpt-3.5-turbo --provider openai --temperature 0.5 --api-key sk-1234567890 --application-context "My application is a cat store"`
 

package/docs/ko/configuration.md

@@ -14,6 +14,9 @@ slugs:
   - concept
   - configuration
 history:
+  - version: 8.0.5
+    date: 2026-02-06
+    changes: AI 구성에 `dataSerialization` 추가
   - version: 8.0.0
     date: 2026-01-22
     changes: Move `importMode` build configuration to `dictionary` configuration.
@@ -883,6 +886,13 @@ Intlayer는 향상된 유연성과 선택권을 위해 여러 AI 공급자를
   - _예시_: `'https://api.openai.com/v1'`
   - _참고_: 로컬 또는 사용자 정의 AI API 엔드포인트를 가리키는 데 사용할 수 있습니다.
 
+- **dataSerialization**:
+  - _타입_: `'json' | 'toon'`
+  - _기본값_: `'json'`
+  - _설명_: Intlayer의 AI 기능에 사용할 데이터 직렬화 형식.
+  - _예시_: `'toon'`
+  - _참고_: `json`: 표준적이고 신뢰할 수 있음; 더 많은 토큰을 사용함. `toon`: 토큰이 적게 들지만 JSON보다 일관성이 떨어짐.
+
 ### 빌드 구성
 
 Intlayer가 애플리케이션의 국제화를 최적화하고 빌드하는 방식을 제어하는 설정입니다.