@intlayer/docs 5.5.8

package/ja/vs_code_extension.md

@@ -0,0 +1,139 @@
+# 公式VS Code拡張機能
+
+## 概要
+
+**Intlayer** は、**React、Next.js、JavaScript** プロジェクトでローカライズされたコンテンツを扱う際の開発者体験を向上させるために設計された、**Intlayer** の公式 Visual Studio Code 拡張機能です。
+
+この拡張機能を使用すると、開発者はコンテンツ辞書に**迅速に移動**し、ローカライズファイルを管理し、強力な自動化コマンドでワークフローを効率化できます。
+
+![Intlayer VS Code Extension](https://github.com/aymericzip/intlayer/blob/main/docs/assets/vs_code_extension_demo.gif)
+
+拡張機能リンク: [https://marketplace.visualstudio.com/items?itemName=Intlayer.intlayer-vs-code-extension](https://marketplace.visualstudio.com/items?itemName=Intlayer.intlayer-vs-code-extension)
+
+## 機能
+
+### 即時ナビゲーション
+
+**定義への移動サポート** – `useIntlayer` キーを `Cmd+Click` (Mac) または `Ctrl+Click` (Windows/Linux) でクリックすると、対応するコンテンツファイルを即座に開きます。  
+**シームレスな統合** – **react-intlayer** および **next-intlayer** プロジェクトとスムーズに連携します。  
+**多言語サポート** – 異なる言語でローカライズされたコンテンツをサポートします。  
+**VS Code 統合** – VS Code のナビゲーションおよびコマンドパレットとスムーズに統合します。
+
+### 辞書管理コマンド
+
+VS Code から直接コンテンツ辞書を管理できます：
+
+- **辞書の構築** (`extension.buildDictionaries`) – プロジェクト構造に基づいてコンテンツファイルを生成します。
+- **辞書のプッシュ** (`extension.pushDictionaries`) – 最新の辞書コンテンツをリポジトリにアップロードします。
+- **辞書のプル** (`extension.pullDictionaries`) – 最新の辞書コンテンツをリポジトリからローカル環境に同期します。
+
+### コンテンツ宣言ジェネレーター
+
+異なる形式で構造化された辞書ファイルを簡単に生成できます：
+
+- **TypeScript (`.ts`)** – `extension.createDictionaryFile.ts`
+- **ES モジュール (`.esm`)** – `extension.createDictionaryFile.esm`
+- **CommonJS (`.cjs`)** – `extension.createDictionaryFile.cjs`
+- **JSON (`.json`)** – `extension.createDictionaryFile.json`
+
+## インストール
+
+**Intlayer** を VS Code Marketplace から直接インストールできます：
+
+1. **VS Code** を開きます。
+2. **拡張機能マーケットプレイス** に移動します。
+3. **"Intlayer"** を検索します。
+4. **インストール** をクリックします。
+
+または、コマンドラインからインストールすることもできます：
+
+```sh
+code --install-extension intlayer
+```
+
+## 使用方法
+
+### クイックナビゲーション
+
+1. **react-intlayer** を使用するプロジェクトを開きます。
+2. 次のような `useIntlayer()` の呼び出しを見つけます：
+
+   ```tsx
+   const content = useIntlayer("app");
+   ```
+
+3. キー（例: `"app"`）を **Command+クリック** (`⌘+Click` on macOS) または **Ctrl+クリック** (Windows/Linux) します。
+4. VS Code が対応する辞書ファイル（例: `src/app.content.ts`）を自動的に開きます。
+
+### コンテンツ辞書の管理
+
+#### 辞書の構築
+
+すべての辞書コンテンツファイルを生成するには：
+
+```sh
+Cmd + Shift + P (macOS) / Ctrl + Shift + P (Windows/Linux)
+```
+
+**Build Dictionaries** を検索してコマンドを実行します。
+
+#### 辞書のプッシュ
+
+最新の辞書コンテンツをアップロードします：
+
+1. **コマンドパレット** を開きます。
+2. **Push Dictionaries** を検索します。
+3. プッシュする辞書を選択して確認します。
+
+#### 辞書のプル
+
+最新の辞書コンテンツを同期します：
+
+1. **コマンドパレット** を開きます。
+2. **Pull Dictionaries** を検索します。
+3. プルする辞書を選択します。
+
+### 辞書ファイルパスのカスタマイズ
+
+デフォルトでは、拡張機能は標準の **Intlayer** プロジェクト構造に従います。ただし、カスタムパスを設定することもできます：
+
+1. **設定 (`Cmd + ,` on macOS / `Ctrl + ,` on Windows/Linux)`** を開きます。
+2. `Intlayer` を検索します。
+3. コンテンツファイルパスの設定を調整します。
+
+## 開発と貢献
+
+貢献したいですか？コミュニティからの貢献を歓迎します！
+
+リポジトリ URL: https://github.com/aymericzip/intlayer-vs-code-extension
+
+### 始め方
+
+リポジトリをクローンして依存関係をインストールします：
+
+```sh
+git clone https://github.com/aymericzip/intlayer-vs-code-extension.git
+cd intlayer-vs-code-extension
+npm install
+```
+
+> `vsce` パッケージを使用して拡張機能をビルドおよび公開するために、`npm` パッケージマネージャーを使用してください。
+
+### 開発モードで実行
+
+1. **VS Code** でプロジェクトを開きます。
+2. `F5` を押して新しい **Extension Development Host** ウィンドウを起動します。
+
+### プルリクエストの送信
+
+拡張機能を改善した場合は、[GitHub](https://github.com/aymericzip/intlayer-vs-code-extension) で PR を送信してください。
+
+## フィードバックと問題
+
+バグを見つけたり、機能リクエストがありますか？**GitHub リポジトリ**で問題を報告してください：
+
+[GitHub Issues](https://github.com/aymericzip/intlayer-vs-code-extension/issues)
+
+## ライセンス
+
+Intlayer は **MIT ライセンス** の下で公開されています。

package/ko/CI_CD.md

@@ -0,0 +1,149 @@
+# CI/CD 파이프라인에서 번역 자동 생성
+
+Intlayer는 콘텐츠 선언 파일에 대한 번역을 자동으로 생성할 수 있습니다. 워크플로우에 따라 이를 달성하는 여러 가지 방법이 있습니다.
+
+## CMS 사용
+
+Intlayer를 사용하면 로컬에서 단일 로케일만 선언하고, 모든 번역은 CMS를 통해 원격으로 관리하는 워크플로우를 채택할 수 있습니다. 이를 통해 콘텐츠와 번역이 코드베이스에서 완전히 분리되어 콘텐츠 편집자에게 더 많은 유연성을 제공하며, 애플리케이션을 다시 빌드하지 않고도 변경 사항을 적용할 수 있는 핫 콘텐츠 리로딩을 가능하게 합니다.
+
+### 예제 구성
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.SPANISH, Locales.FRENCH],
+    requiredLocales: [Locales.ENGLISH], // 선택적 로케일은 원격으로 관리됩니다.
+    defaultLocale: Locales.ENGLISH,
+  },
+  editor: {
+    dictionaryPriorityStrategy: "distant_first", // 원격 콘텐츠가 우선 순위를 가집니다.
+
+    applicationURL: process.env.APPLICATION_URL, // CMS에서 사용하는 애플리케이션 URL
+
+    clientId: process.env.INTLAYER_CLIENT_ID, // CMS 자격 증명
+    clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+  },
+  ai: {
+    applicationContext: "This is a test application", // 일관된 번역 생성을 보장하는 데 도움을 줍니다.
+  },
+};
+
+export default config;
+```
+
+CMS에 대한 자세한 내용은 [공식 문서](https://github.com/aymericzip/intlayer/blob/main/docs/ko/intlayer_CMS.md)를 참조하세요.
+
+## Husky 사용
+
+[Husky](https://typicode.github.io/husky/)를 사용하여 로컬 Git 워크플로우에 번역 생성을 통합할 수 있습니다.
+
+### 예제 구성
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.SPANISH, Locales.FRENCH],
+    requiredLocales: [Locales.ENGLISH], // 선택적 로케일은 원격으로 처리됩니다.
+    defaultLocale: Locales.ENGLISH,
+  },
+  editor: {
+    clientId: process.env.INTLAYER_CLIENT_ID,
+    clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+  },
+  ai: {
+    provider: "openai",
+    apiKey: process.env.OPENAI_API_KEY, // 자신의 API 키를 사용하세요.
+
+    applicationContext: "This is a test application", // 일관된 번역 생성을 보장하는 데 도움을 줍니다.
+  },
+};
+
+export default config;
+```
+
+```bash fileName=".husky/pre-push"
+npx intlayer build                          # 사전이 최신 상태인지 확인
+npx intlayer fill --unpushed --mode fill    # 누락된 콘텐츠만 채우고, 기존 콘텐츠는 업데이트하지 않음
+```
+
+> Intlayer CLI 명령과 사용법에 대한 자세한 내용은 [CLI 문서](https://github.com/aymericzip/intlayer/blob/main/docs/ko/intlayer_cli.md)를 참조하세요.
+
+> 저장소에 여러 앱이 있고 각각 별도의 intlayer 인스턴스를 사용하는 경우, 다음과 같이 `--base-dir` 인수를 사용할 수 있습니다:
+
+```bash fileName=".husky/pre-push"
+# 앱 1
+npx intlayer build --base-dir ./app1
+npx intlayer fill --base-dir ./app1 --unpushed --mode fill
+
+# 앱 2
+npx intlayer build --base-dir ./app2
+npx intlayer fill --base-dir ./app2 --unpushed --mode fill
+```
+
+## GitHub Actions 사용
+
+Intlayer는 사전 채우기 및 사전 콘텐츠 검토를 위한 CLI 명령을 제공합니다. 이를 GitHub Actions를 사용하여 CI/CD 워크플로우에 통합할 수 있습니다.
+
+```yaml fileName=".github/workflows/intlayer-translate.yml"
+name: Intlayer Auto-Fill
+on:
+  push:
+    branches: [ main ]
+    paths:
+      - 'src/**'
+  pull_request:
+    branches: [ main ]
+    paths:
+      - 'src/**'
+  workflow_dispatch: {}
+
+concurrency:
+  group: 'autofill-${{ github.ref }}'
+  cancel-in-progress: true
+
+jobs:
+  autofill:
+    runs-on: ubuntu-latest
+    env:
+      INTLAYER_CLIENT_ID: ${{ secrets.INTLAYER_CLIENT_ID }}
+      INTLAYER_CLIENT_SECRET: ${{ secrets.INTLAYER_CLIENT_SECRET }}
+      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+
+    steps:
+      - name: ⬇️ 저장소 체크아웃
+        uses: actions/checkout@v3
+        with:
+          persist-credentials: true
+
+      - name: 🟢 Node.js 설정
+        uses: actions/setup-node@v3
+        with:
+          node-version: 20
+
+      - name: 📦 의존성 설치
+        run: npm ci
+
+      - name: ⚙️ Intlayer 프로젝트 빌드
+        run: npx intlayer build
+
+      - name: 🤖 누락된 번역 자동 채우기
+        run: npx intlayer fill --git-diff --mode fill
+
+      - name: 📤 번역 PR 생성 또는 업데이트
+        uses: peter-evans/create-pull-request@v4
+        with:
+          commit-message: chore: 누락된 번역 자동 채우기 [skip ci]
+          branch: auto-translations
+          title: chore: 누락된 번역 업데이트
+          labels: translation, automated
+```
+
+> Husky와 마찬가지로 모노레포의 경우 `--base-dir` 인수를 사용하여 각 앱을 순차적으로 처리할 수 있습니다.
+
+> 기본적으로 `--git-diff` 인수는 기본(기본값 `origin/main`)에서 현재 브랜치(기본값: `HEAD`)까지의 변경 사항이 포함된 사전을 필터링합니다.
+
+> Intlayer CLI 명령과 사용법에 대한 자세한 내용은 [CLI 문서](https://github.com/aymericzip/intlayer/blob/main/docs/ko/intlayer_cli.md)를 참조하세요.

package/ko/autoFill.md

@@ -0,0 +1,157 @@
+# 자동 채우기 콘텐츠 선언 파일
+
+**자동 채우기 콘텐츠 선언 파일**은 개발 워크플로우를 가속화하는 방법입니다.
+
+자동 채우기 메커니즘은 콘텐츠 선언 파일 간의 _마스터-슬레이브_ 관계를 통해 작동합니다. 메인(마스터) 파일이 업데이트되면 Intlayer는 자동으로 이러한 변경사항을 파생(자동 채워진) 선언 파일에 적용합니다.
+
+```ts fileName="src/components/example/example.content.ts"
+import { Locales, type Dictionary } from "intlayer";
+
+const exampleContent = {
+  key: "example",
+  locale: Locales.ENGLISH,
+  autoFill: "./example.content.json",
+  content: {
+    contentExample: "This is an example of content",
+  },
+} satisfies Dictionary;
+
+export default exampleContent;
+```
+
+다음은 `autoFill` 지시문을 사용하는 [언어별 콘텐츠 선언 파일](https://github.com/aymericzip/intlayer/blob/main/docs/ko/per_locale_file.md)입니다.
+
+그런 다음 다음 명령을 실행하면:
+
+```bash
+npx intlayer fill --file 'src/components/example/example.content.ts'
+```
+
+Intlayer는 자동으로 `src/components/example/example.content.json`에 파생 선언 파일을 생성하고, 메인 파일에서 아직 선언되지 않은 모든 언어를 채웁니다.
+
+```json5 fileName="src/components/example/example.content.json"
+{
+  "key": "example",
+  "content": {
+    "contentExample": {
+      "nodeType": "translation",
+      "translation": {
+        "fr": "Ceci est un exemple de contenu",
+        "es": "Este es un ejemplo de contenido",
+      },
+    },
+  },
+}
+```
+
+이후 두 선언 파일은 하나의 사전으로 병합되며, 표준 `useIntlayer("example")` 훅(react) / 컴포저블(vue)을 사용하여 접근할 수 있습니다.
+
+## 자동 채우기 파일 형식
+
+자동 채우기 선언 파일의 권장 형식은 **JSON**이며, 이는 형식 제약을 피하는 데 도움이 됩니다. 그러나 Intlayer는 `.ts`, `.js`, `.mjs`, `.cjs` 등의 형식도 지원합니다.
+
+```ts fileName="src/components/example/example.content.ts"
+const exampleContent = {
+  key: "example",
+  autoFill: "./example.filled.content.ts",
+  content: {
+    // 콘텐츠
+  },
+};
+```
+
+이것은 다음 위치에 파일을 생성합니다:
+
+```
+src/components/example/example.filled.content.ts
+```
+
+> `.js`, `.ts` 등의 파일 생성은 다음과 같이 작동합니다:
+
+> - 파일이 이미 존재하는 경우, Intlayer는 AST(추상 구문 트리)를 사용하여 각 필드를 찾고 누락된 번역을 삽입합니다.
+
+> - 파일이 존재하지 않는 경우, Intlayer는 콘텐츠 선언 파일의 기본 템플릿을 사용하여 생성합니다.
+
+## 절대 경로
+
+`autoFill` 필드는 절대 경로도 지원합니다.
+
+```ts fileName="src/components/example/example.content.ts"
+const exampleContent = {
+  key: "example",
+  autoFill: "/messages/example.content.json",
+  content: {
+    // 콘텐츠
+  },
+};
+```
+
+이것은 다음 위치에 파일을 생성합니다:
+
+```
+/messages/example.content.json
+```
+
+## 언어별 콘텐츠 선언 파일 자동 생성
+
+`autoFill` 필드는 **언어별** 콘텐츠 선언 파일의 생성도 지원합니다.
+
+```ts fileName="src/components/example/example.content.ts"
+const exampleContent = {
+  key: "example",
+  autoFill: {
+    fr: "./example.fr.content.json",
+    es: "./example.es.content.json",
+  },
+  content: {
+    // 콘텐츠
+  },
+};
+```
+
+이것은 두 개의 별도 파일을 생성합니다:
+
+- `src/components/example/example.fr.content.json`
+- `src/components/example/example.es.content.json`
+
+## 특정 언어 자동 채우기 필터링
+
+`autoFill` 필드에 객체를 사용하면 필터를 적용하고 특정 언어 파일만 생성할 수 있습니다.
+
+```ts fileName="src/components/example/example.content.ts"
+const exampleContent = {
+  key: "example",
+  autoFill: {
+    fr: "./example.fr.content.json",
+  },
+  content: {
+    // 콘텐츠
+  },
+};
+```
+
+이것은 프랑스어 번역 파일만 생성합니다.
+
+## 경로 변수
+
+`autoFill` 경로 내에서 변수를 사용하여 생성된 파일의 대상 경로를 동적으로 해결할 수 있습니다.
+
+**사용 가능한 변수:**
+
+- `{{locale}}` – 언어 코드(예: `fr`, `es`)
+- `{{key}}` – 사전 키(예: `example`)
+
+```ts fileName="src/components/example/example.content.ts"
+const exampleContent = {
+  key: "example",
+  autoFill: "/messages/{{locale}}/{{key}}.content.json",
+  content: {
+    // 콘텐츠
+  },
+};
+```
+
+이것은 다음을 생성합니다:
+
+- `/messages/fr/example.content.json`
+- `/messages/es/example.content.json`