@intlayer/docs 5.8.1 → 6.0.0-canary.0

package/docs/ja/testing.md

@@ -0,0 +1,200 @@
+---
+createdAt: 2025-03-01
+updatedAt: 2025-09-20
+title: コンテンツのテスト
+description: Intlayerを使ったコンテンツのテスト方法を紹介します。
+keywords:
+  - テスト
+  - Intlayer
+  - 国際化
+  - CMS
+  - コンテンツ管理システム
+  - ビジュアルエディタ
+slugs:
+  - doc
+  - testing
+---
+
+# コンテンツのテスト
+
+このガイドでは、辞書が完全であることを自動的に検証し、出荷前に翻訳漏れを検出し、アプリ内のローカライズされたUIをテストする方法を説明します。
+
+---
+
+## テストできること
+
+- **翻訳漏れ**: 必須のロケールが辞書に欠けている場合、CIを失敗させます。
+- **ローカライズされたUIのレンダリング**: 特定のロケールプロバイダーでコンポーネントをレンダリングし、表示されるテキストや属性を検証します。
+- **ビルド時の監査**: CLIを使ってローカルで簡単な監査を実行します。
+
+---
+
+## クイックスタート: CLIによる監査
+
+プロジェクトのルートから監査を実行します:
+
+```bash
+npx intlayer content test
+```
+
+便利なフラグ:
+
+- `--env-file [path]`: ファイルから環境変数を読み込みます。
+- `-e, --env [name]`: 環境プロファイルを選択します。
+- `--base-dir [path]`: 解決のためのアプリのベースディレクトリを設定します。
+- `--verbose`: 詳細なログを表示します。
+- `--prefix [label]`: ログ行にプレフィックスを付けます。
+
+注意: CLIは詳細なレポートを出力しますが、失敗時に非ゼロで終了しません。CIのゲーティングには、必須ロケールの欠落がゼロであることをアサートするユニットテスト（以下）を追加してください。
+
+---
+
+## プログラムによるテスト (Vitest/Jest)
+
+Intlayer CLI APIを使って、必須ロケールの翻訳漏れがないことをアサートします。
+
+```ts file=i18n.test.ts
+/* @vitest-environment node */
+import { listMissingTranslations } from "intlayer/cli";
+import { describe, expect, it } from "vitest";
+
+describe("translations", () => {
+  it("必須のロケールが欠落していないこと", () => {
+    const result = listMissingTranslations();
+
+    if (result.missingRequiredLocales.length > 0) {
+      // テストがローカルまたはCIで失敗したときに役立ちます
+      console.log(result.missingTranslations);
+    }
+
+    expect(result.missingRequiredLocales).toHaveLength(0);
+  });
+});
+```
+
+Jestの同等コード:
+
+```ts file=i18n.test.ts
+import { listMissingTranslations } from "intlayer/cli";
+
+test("必須のロケールが欠落していないこと", () => {
+  const result = listMissingTranslations();
+
+  if (result.missingRequiredLocales.length > 0) {
+    // eslint-disable-next-line no-console
+    console.log(result.missingTranslations);
+  }
+
+  expect(result.missingRequiredLocales).toHaveLength(0);
+});
+```
+
+動作の仕組み：
+
+- Intlayerは設定（locales、requiredLocales）と宣言された辞書を読み込み、以下を報告します：
+  - `missingTranslations`：キーごとに、どのロケールが欠落しているか、どのファイルからかを示します。
+  - `missingLocales`：欠落しているすべてのロケールの集合。
+  - `missingRequiredLocales`：`requiredLocales`に限定された部分集合（`requiredLocales`が設定されていない場合はすべてのロケール）。
+
+---
+
+## ローカライズされたUIのテスト（React / Next.js）
+
+Intlayerプロバイダーの下でコンポーネントをレンダリングし、表示されている内容を検証します。
+
+Reactの例（Testing Library）：
+
+```tsx
+import { IntlayerProvider } from "react-intlayer/client";
+import { render, screen } from "@testing-library/react";
+import { MyComponent } from "./MyComponent";
+
+test("renders localized title in English", () => {
+  render(
+    <IntlayerProvider locale="en-US">
+      <MyComponent />
+    </IntlayerProvider>
+  );
+
+  expect(screen.getByText("期待される英語のタイトル")).toBeInTheDocument();
+});
+```
+
+Next.js（App Router）例：フレームワークのラッパーを使用します：
+
+```tsx
+import { IntlayerClientProvider } from "next-intlayer/client";
+import { render, screen } from "@testing-library/react";
+import { MyPage } from "./MyPage";
+
+test("フランス語でローカライズされた見出しをレンダリングする", () => {
+  render(
+    <IntlayerClientProvider locale="fr-FR">
+      <MyPage />
+    </IntlayerClientProvider>
+  );
+  expect(
+    screen.getByRole("heading", { name: "期待されるタイトル" })
+  ).toBeInTheDocument();
+});
+```
+
+ヒント：
+
+- 属性の生の文字列値（例：`aria-label`）が必要な場合は、Reactの`useIntlayer`から返される`.value`フィールドにアクセスしてください。
+- コンポーネントと辞書を同じ場所に配置しておくことで、ユニットテストやクリーンアップが容易になります。
+
+---
+
+## 継続的インテグレーション
+
+必要な翻訳が欠落している場合にビルドを失敗させるテストを追加します。
+
+`package.json`:
+
+```json
+{
+  "scripts": {
+    "test:i18n": "vitest run -c"
+  }
+}
+```
+
+GitHub Actions の例:
+
+```yaml
+name: CI
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+      - run: npm run test:i18n
+```
+
+オプション: テストと並行して、人間が読みやすい要約を得るために CLI 監査を実行します:
+
+```bash
+npx intlayer content test --verbose
+```
+
+---
+
+## トラブルシューティング
+
+- Intlayerの設定で`locales`および（オプションで）`requiredLocales`が定義されていることを確認してください。
+- アプリが動的またはリモートの辞書を使用している場合は、辞書が利用可能な環境でテストを実行してください。
+- 混在するモノレポの場合は、CLIに正しいアプリケーションルートを指示するために`--base-dir`を使用してください。
+
+---
+
+## ドキュメント履歴
+
+| バージョン | 日付       | 変更内容   |
+| ---------- | ---------- | ---------- |
+| 6.0.0      | 2025-09-20 | テスト導入 |

package/docs/ko/autoFill.md

@@ -1,8 +1,8 @@
 ---
 createdAt: 2025-03-13
-updatedAt: 2025-06-29
+updatedAt: 2025-09-20
 title: 자동 채우기
-description: Intlayer에서 미리 정의된 패턴을 기반으로 콘텐츠를 자동으로 채우는 자동 채우기 기능을 사용하는 방법을 알아보세요. 이 문서를 따라 프로젝트에서 자동 채우기 기능을 효율적으로 구현할 수 있습니다.
+description: Intlayer에서 자동 채우기 기능을 사용하여 미리 정의된 패턴에 따라 콘텐츠를 자동으로 채우는 방법을 알아보세요. 이 문서를 따라 프로젝트에서 자동 채우기 기능을 효율적으로 구현할 수 있습니다.
 keywords:
   - 자동 채우기
   - 콘텐츠 자동화
@@ -19,8 +19,9 @@ slugs:
 
 # 자동 채우기 콘텐츠 선언 파일 번역
 
-**자동 채우기 콘텐츠 선언 파일**은 개발 워크플로우를 가속화하는 방법입니다.  
-자동 채우기 메커니즘은 콘텐츠 선언 파일 간의 _마스터-슬레이브_ 관계를 통해 작동합니다. 메인(마스터) 파일이 업데이트되면 Intlayer는 해당 변경 사항을 파생(자동 채우기) 선언 파일에 자동으로 적용합니다.
+**자동 채우기 콘텐츠 선언 파일**은 개발 워크플로우를 가속화하는 방법입니다.
+
+자동 채우기 메커니즘은 콘텐츠 선언 파일 간의 _마스터-슬레이브_ 관계를 통해 작동합니다. 메인(마스터) 파일이 업데이트되면 Intlayer가 파생(자동 채우기된) 선언 파일에 해당 변경 사항을 자동으로 적용합니다.
 
 ```ts fileName="src/components/example/example.content.ts"
 import { Locales, type Dictionary } from "intlayer";
@@ -30,14 +31,14 @@ const exampleContent = {
   locale: Locales.ENGLISH,
   autoFill: "./example.content.json",
   content: {
-    contentExample: "이것은 콘텐츠 예시입니다",
+    contentExample: "이것은 콘텐츠의 예시입니다",
   },
 } satisfies Dictionary;
 
 export default exampleContent;
 ```
 
-다음은 `autoFill` 지시어를 사용하는 [로케일별 콘텐츠 선언 파일](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/per_locale_file.md)입니다.
+다음은 `autoFill` 지시어를 사용한 [로케일별 콘텐츠 선언 파일](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/per_locale_file.md)입니다.
 
 그런 다음, 다음 명령어를 실행하면:
 
@@ -62,11 +63,11 @@ Intlayer는 메인 파일에 아직 선언되지 않은 모든 로케일을 채
 }
 ```
 
-그 후, 두 선언 파일은 단일 사전으로 병합되어 표준 `useIntlayer("example")` 훅(react) / 컴포저블(vue)을 사용하여 접근할 수 있습니다.
+그 후, 두 선언 파일은 단일 사전으로 병합되어 표준 `useIntlayer("example")` 훅(react) / 컴포저블(vue)을 통해 접근할 수 있습니다.
 
 ## 자동 채워진 파일 형식
 
-자동 채워진 선언 파일에 권장되는 형식은 **JSON**이며, 이는 형식 제약을 피하는 데 도움이 됩니다. 그러나 Intlayer는 `.ts`, `.js`, `.mjs`, `.cjs` 및 기타 형식도 지원합니다.
+자동 채워진 선언 파일에 권장되는 형식은 **JSON**으로, 형식 제약을 피하는 데 도움이 됩니다. 그러나 Intlayer는 `.ts`, `.js`, `.mjs`, `.cjs` 및 기타 형식도 지원합니다.
 
 ```ts fileName="src/components/example/example.content.ts"
 const exampleContent = {
@@ -84,7 +85,7 @@ const exampleContent = {
 src/components/example/example.filled.content.ts
 ```
 
-> `.js`, `.ts` 및 유사한 파일의 생성 방식은 다음과 같습니다:
+> `.js`, `.ts` 및 유사한 파일 생성은 다음과 같이 작동합니다:
 >
 > - 파일이 이미 존재하는 경우, Intlayer는 AST(추상 구문 트리)를 사용하여 각 필드를 찾아 누락된 번역을 삽입합니다.
 > - 파일이 존재하지 않는 경우, Intlayer는 기본 콘텐츠 선언 파일 템플릿을 사용하여 파일을 생성합니다.
@@ -111,7 +112,7 @@ const exampleContent = {
 
 ## 로케일별 콘텐츠 선언 파일 자동 생성
 
-`autoFill` 필드는 **로케일별** 콘텐츠 선언 파일 생성도 지원합니다.
+`autoFill` 필드는 **로케일별** 콘텐츠 선언 파일 생성을 지원합니다.
 
 ```ts fileName="src/components/example/example.content.ts"
 const exampleContent = {
@@ -121,7 +122,7 @@ const exampleContent = {
     es: "./example.es.content.json",
   },
   content: {
-    // 여기에 내용을 작성하세요
+    // 귀하의 콘텐츠
   },
 };
 ```
@@ -131,7 +132,9 @@ const exampleContent = {
 - `src/components/example/example.fr.content.json`
 - `src/components/example/example.es.content.json`
 
-## 특정 로케일 자동 채우기 필터
+> 이 경우, 객체에 모든 로케일이 포함되어 있지 않으면 Intlayer는 나머지 로케일의 생성을 건너뜁니다.
+
+## 특정 로케일 자동 채우기 필터링
 
 `autoFill` 필드에 객체를 사용하면 필터를 적용하여 특정 로케일 파일만 생성할 수 있습니다.
 
@@ -142,7 +145,7 @@ const exampleContent = {
     fr: "./example.fr.content.json",
   },
   content: {
-    // 여기에 내용을 작성하세요
+    // 귀하의 콘텐츠
   },
 };
 ```
@@ -156,9 +159,10 @@ const exampleContent = {
 **사용 가능한 변수:**
 
 - `{{locale}}` – 로케일 코드 (예: `fr`, `es`)
+- `{{fileName}}` – 파일 이름 (예: `index`)
 - `{{key}}` – 사전 키 (예: `example`)
 
-```ts fileName="src/components/example/example.content.ts"
+```ts fileName="src/components/example/index.content.ts"
 const exampleContent = {
   key: "example",
   autoFill: "/messages/{{locale}}/{{key}}.content.json",
@@ -168,11 +172,30 @@ const exampleContent = {
 };
 ```
 
-이것은 다음을 생성합니다:
+이 코드는 다음 파일들을 생성합니다:
 
 - `/messages/fr/example.content.json`
 - `/messages/es/example.content.json`
 
+```ts fileName="src/components/example/index.content.ts"
+const exampleContent = {
+  key: "example",
+  autoFill: "./{{fileName}}.content.json",
+  content: {
+    // 여기에 내용을 작성하세요
+  },
+};
+```
+
+이 코드는 다음 파일들을 생성합니다:
+
+- `./index.content.json`
+- `./index.content.json`
+
 ## 문서 이력
 
-- 5.5.10 - 2025-06-29: 초기 이력 생성
+| 버전    | 날짜        | 변경 사항                   |
+| ------- | ----------- | --------------------------- |
+| 6.0.0   | 2025-09-20  | 전역 구성 추가              |
+| 6.0.0   | 2025-09-17  | `{{fileName}}` 변수 추가    |
+| 5.5.10  | 2025-06-29  | 이력 초기화                 |