@intlayer/docs 5.7.7 → 5.8.0-canary.0

package/docs/ja/CI_CD.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-05-20
-updatedAt: 2025-06-29
+updatedAt: 2025-08-13
 title: CI/CD 統合
 description: Intlayer を CI/CD パイプラインに統合して、自動化されたコンテンツ管理とデプロイメントを実現する方法を学びます。
 keywords:
@@ -19,11 +19,11 @@ slugs:
 
 # CI/CD パイプラインでの翻訳の自動生成
 
-Intlayer は、コンテンツ宣言ファイルの翻訳を自動的に生成することを可能にします。ワークフローに応じて、これを実現する複数の方法があります。
+Intlayer は、コンテンツ宣言ファイルの翻訳を自動生成することを可能にします。ワークフローに応じて、これを実現する複数の方法があります。
 
 ## CMS の利用
 
-Intlayer を使用すると、ローカルでは単一のロケールのみを宣言し、すべての翻訳を CMS を通じてリモートで管理するワークフローを採用できます。これにより、コンテンツと翻訳がコードベースから完全に切り離され、コンテンツ編集者にとってより柔軟性が高まり、ホットコンテンツリロード（変更を適用するためにアプリケーションを再ビルドする必要なし）が可能になります。
+Intlayer を使用すると、ローカルでは単一のロケールのみを宣言し、すべての翻訳は CMS を通じてリモートで管理するワークフローを採用できます。これにより、コンテンツと翻訳がコードベースから完全に切り離され、コンテンツ編集者にとってより柔軟性が提供され、ホットコンテンツリロード（変更を適用するためにアプリケーションを再ビルドする必要なし）が可能になります。
 
 ### 設定例
 
@@ -54,7 +54,7 @@ export default config;
 
 CMSの詳細については、[公式ドキュメント](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/intlayer_CMS.md)を参照してください。
 
-## Huskyの使用方法
+## Huskyの使用
 
 [Husky](https://typicode.github.io/husky/)を使用して、ローカルのGitワークフローに翻訳生成を統合できます。
 
@@ -77,7 +77,7 @@ const config: IntlayerConfig = {
     provider: "openai",
     apiKey: process.env.OPENAI_API_KEY, // ご自身のAPIキーを使用してください
 
-    applicationContext: "これはテストアプリケーションです", // 一貫した翻訳生成を確保するのに役立ちます
+    applicationContext: "This is a test application", // 一貫した翻訳生成を支援します
   },
 };
 
@@ -89,7 +89,7 @@ npx intlayer build                          # 辞書が最新であることを
 npx intlayer fill --unpushed --mode fill    # 欠落しているコンテンツのみを埋め、既存のものは更新しません
 ```
 
-> IntlayerのCLIコマンドとその使用方法の詳細については、[CLIドキュメント](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/intlayer_cli.md)を参照してください。
+> Intlayer CLIコマンドとその使用方法の詳細については、[CLIドキュメント](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/intlayer_cli.md)を参照してください。
 
 > リポジトリ内に複数のアプリがあり、それぞれ別のintlayerインスタンスを使用している場合は、次のように`--base-dir`引数を使用できます。
 
@@ -103,70 +103,96 @@ npx intlayer build --base-dir ./app2
 npx intlayer fill --base-dir ./app2 --unpushed --mode fill
 ```
 
-## GitHub Actionsの使用方法
+## GitHub Actionsの使用
 
-Intlayerは、辞書の内容を自動入力およびレビューするためのCLIコマンドを提供しています。これはGitHub Actionsを使用してCI/CDワークフローに統合することができます。
+Intlayerは辞書コンテンツの自動入力およびレビューを行うCLIコマンドを提供しています。これはGitHub Actionsを使用してCI/CDワークフローに統合することができます。
 
 ```yaml fileName=".github/workflows/intlayer-translate.yml"
 name: Intlayer 自動入力
+# このワークフローのトリガー条件
 on:
-  push:
-    branches: [ main ]
-    paths:
-      - 'src/**'
   pull_request:
-    branches: [ main ]
-    paths:
-      - 'src/**'
-  workflow_dispatch: {}
+    branches:
+      - "main"
+
+permissions:
+  contents: write
+  pull-requests: write
 
 concurrency:
-  group: 'autofill-${{ github.ref }}'
+  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 }}
+      # OpenAI
+      AI_MODEL: openai
+      AI_PROVIDER: gpt-5-mini
+      AI_API_KEY: ${{ secrets.AI_API_KEY }}
 
     steps:
+      # ステップ1: リポジトリから最新コードを取得
       - name: ⬇️ リポジトリをチェックアウト
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
-          persist-credentials: true
+          persist-credentials: true # PR作成のための認証情報を保持
+          fetch-depth: 0 # 差分解析のために完全なGit履歴を取得
 
-      - name: 🟢 Node.js のセットアップ
-        uses: actions/setup-node@v3
+      # ステップ 2: Node.js環境のセットアップ
+      - name: 🟢 Node.jsをセットアップ
+        uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 20 # 安定性のためNode.js 20 LTSを使用
 
-      - name: 📦 依存関係のインストール
-        run: npm ci
+      # ステップ 3: プロジェクト依存関係のインストール
+      - name: 📦 依存関係をインストール
+        run: npm install
 
-      - name: ⚙️ Intlayer プロジェクトのビルド
-        run: npx intlayer build
+      # ステップ 4: 翻訳管理のためにIntlayer CLIをグローバルインストール
+      - name: 📦 Intlayerをインストール
+        run: npm install -g intlayer-cli
 
-      - name: 🤖 欠落している翻訳の自動補完
-        run: npx intlayer fill --git-diff --mode fill
+      # ステップ 5: 翻訳ファイルを生成するためにIntlayerプロジェクトをビルド
+      - name: ⚙️ Intlayerプロジェクトをビルド
+        run: npx intlayer build
 
-      - name: 📤 翻訳プルリクエストの作成または更新
-        uses: peter-evans/create-pull-request@v4
-        with:
-          commit-message: chore: auto-fill missing translations [skip ci]
-          branch: auto-translations
-          title: chore: update missing translations
-          labels: translation, automated
+      # ステップ 6: AIを使って不足している翻訳を自動で埋める
+      - name: 🤖 欠落している翻訳を自動入力
+        run: npx intlayer fill --git-diff --mode fill --provider $AI_PROVIDER --model $AI_MODEL --api-key $AI_API_KEY
+
+      # ステップ7: 変更があるか確認し、あればコミットする
+      - name: � 変更を確認
+        id: check-changes
+        run: |
+          if [ -n "$(git status --porcelain)" ]; then
+            echo "has-changes=true" >> $GITHUB_OUTPUT
+          else
+            echo "has-changes=false" >> $GITHUB_OUTPUT
+          fi
+
+      # ステップ8: 変更があればコミットしてプッシュする
+      - name: 📤 変更をコミットしてプッシュ
+        if: steps.check-changes.outputs.has-changes == 'true'
+        run: |
+          git config --local user.email "action@github.com"
+          git config --local user.name "GitHub Action"
+          git add .
+          git commit -m "chore: auto-fill missing translations [skip ci]"
+          git push origin HEAD:${{ github.head_ref }}
 ```
 
-> Huskyの場合と同様に、モノレポの場合は `--base-dir` 引数を使用して各アプリを順次処理することができます。
+環境変数を設定するには、GitHub → 設定 → Secrets and variables → Actions に移動し、シークレット（API_KEY）を追加してください。
+
+> Huskyの場合と同様に、モノレポの場合は `--base-dir` 引数を使用して各アプリを順番に処理できます。
 
 > デフォルトでは、`--git-diff` 引数はベース（デフォルトは `origin/main`）から現在のブランチ（デフォルトは `HEAD`）への変更を含む辞書をフィルタリングします。
 
-> Intlayer CLI コマンドとその使用方法の詳細については、[CLIドキュメント](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/intlayer_cli.md)を参照してください。
+> Intlayer CLIコマンドとその使用方法の詳細については、[CLIドキュメント](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/intlayer_cli.md)を参照してください。
 
 ## ドキュメント履歴
 
-- 5.5.10 - 2025-06-29: 履歴の初期化
+| バージョン | 日付       | 変更内容     |
+| ---------- | ---------- | ------------ |
+| 5.5.10     | 2025-06-29 | 履歴の初期化 |

package/docs/ja/formatters.md

@@ -0,0 +1,261 @@
+---
+createdAt: 2024-08-13
+updatedAt: 2025-08-20
+title: フォーマッター
+description: 数字、パーセンテージ、通貨、日付、相対時間、単位、コンパクト表記のためのIntlベースのロケール対応フォーマットユーティリティ。キャッシュされたIntlヘルパーを含む。
+keywords:
+  - フォーマッター
+  - Intl
+  - 数字
+  - 通貨
+  - パーセンテージ
+  - 日付
+  - 相対時間
+  - 単位
+  - コンパクト
+  - 国際化
+slugs:
+  - doc
+  - formatters
+---
+
+# Intlayer フォーマッター
+
+## 概要
+
+Intlayerは、ネイティブの`Intl` APIの上に構築された軽量ヘルパー群と、重いフォーマッターを繰り返し構築するのを避けるためのキャッシュされた`Intl`ラッパーを提供します。これらのユーティリティは完全にロケール対応で、メインの`intlayer`パッケージから使用できます。
+
+### インポート
+
+```ts
+import {
+  Intl,
+  number,
+  percentage,
+  currency,
+  date,
+  relativeTime,
+  units,
+  compact,
+} from "intlayer";
+```
+
+Reactを使用している場合は、フックも利用可能です。詳細は`react-intlayer/format`を参照してください。
+
+## キャッシュされたIntl
+
+エクスポートされる`Intl`は、グローバルな`Intl`の薄いキャッシュラッパーです。`NumberFormat`、`DateTimeFormat`、`RelativeTimeFormat`のインスタンスをメモ化し、同じフォーマッターを繰り返し再構築するのを防ぎます。
+
+フォーマッターの構築は比較的コストがかかるため、このキャッシュにより動作を変えずにパフォーマンスが向上します。このラッパーはネイティブの`Intl`と同じAPIを公開しているため、使用方法は同一です。
+
+- キャッシュはプロセス単位で行われ、呼び出し元には透過的です。
+
+> 環境に`Intl.DisplayNames`が存在しない場合、開発時のみの警告が一度だけ表示されます（ポリフィルの検討を推奨）。
+
+例:
+
+```ts
+import { Intl } from "intlayer";
+
+const numberFormat = new Intl.NumberFormat("en-GB", {
+  style: "currency",
+  currency: "GBP",
+});
+numberFormat.format(1234.5); // "£1,234.50"
+```
+
+## フォーマッター
+
+以下のすべてのヘルパーは `intlayer` からエクスポートされています。
+
+### `number(value, options?)`
+
+ロケールに応じた区切りと小数点を使用して数値をフォーマットします。
+
+- **value**: `number | string`
+- **options**: `Intl.NumberFormatOptions & { locale?: LocalesValues }`
+
+例:
+
+```ts
+import { number } from "intlayer";
+
+number(123456.789); // "123,456.789"（en-USの場合）
+number("1000000", { locale: "fr" }); // "1 000 000"
+number(1234.5, { minimumFractionDigits: 2 }); // "1,234.50"
+```
+
+### `percentage(value, options?)`
+
+数値をパーセント文字列としてフォーマットします。
+
+動作: 1より大きい値は全体のパーセンテージとして解釈され、正規化されます（例：`25` → `25%`、`0.25` → `25%`）。
+
+- **value**: `number | string`
+- **options**: `Intl.NumberFormatOptions & { locale?: LocalesValues }`
+
+例:
+
+```ts
+import { percentage } from "intlayer";
+
+percentage(0.25); // "25%"
+percentage(25); // "25%"
+percentage(0.237, { minimumFractionDigits: 1 }); // "23.7%"
+```
+
+### `currency(value, options?)`
+
+値をローカライズされた通貨としてフォーマットします。デフォルトは小数点以下2桁の`USD`です。
+
+- **value**: `number | string`
+- **options**: `Intl.NumberFormatOptions & { locale?: LocalesValues }`
+  - 共通フィールド: `currency`（例: `"EUR"`）、`currencyDisplay`（`"symbol" | "code" | "name"`）
+
+例:
+
+```ts
+import { currency } from "intlayer";
+
+currency(1234.5, { currency: "EUR" }); // "€1,234.50"
+currency("5000", { locale: "fr", currency: "CAD", currencyDisplay: "code" }); // "5 000,00 CAD"
+```
+
+### `date(date, optionsOrPreset?)`
+
+`Intl.DateTimeFormat` を使用して日付/時刻の値をフォーマットします。
+
+- **date**: `Date | string | number`
+- **optionsOrPreset**: `Intl.DateTimeFormatOptions & { locale?: LocalesValues }` または以下のプリセットのいずれか：
+  - プリセット: `"short" | "long" | "dateOnly" | "timeOnly" | "full"`
+
+例:
+
+```ts
+import { date } from "intlayer";
+
+date(new Date(), "short"); // 例: "08/02/25, 14:30"
+date("2025-08-02T14:30:00Z", { locale: "fr", month: "long", day: "numeric" }); // "2 août"
+```
+
+### `relativeTime(from, to = new Date(), options?)`
+
+`Intl.RelativeTimeFormat` を使用して、2つの時点間の相対時間をフォーマットします。
+
+/// "now" を最初の引数に、対象の時刻を2番目の引数に渡すことで、自然な表現を得られます。
+
+- **from**: `Date | string | number`
+- **to**: `Date | string | number`（デフォルトは `new Date()`）
+- **options**: `{ locale?: LocalesValues; unit?: Intl.RelativeTimeFormatUnit; numeric?: Intl.RelativeTimeFormatNumeric; style?: Intl.RelativeTimeFormatStyle }`
+  - デフォルトの `unit` は `"second"` です。
+
+例:
+
+```ts
+import { relativeTime } from "intlayer";
+
+const now = new Date();
+const in3Days = new Date(now.getTime() + 3 * 864e5);
+relativeTime(now, in3Days, { unit: "day" }); // "in 3 days"
+
+const twoHoursAgo = new Date(now.getTime() - 2 * 3600e3);
+relativeTime(now, twoHoursAgo, { unit: "hour", numeric: "auto" }); // "2 hours ago"
+```
+
+### `units(value, options?)`
+
+数値を `Intl.NumberFormat` の `style: 'unit'` を使用してローカライズされた単位文字列としてフォーマットします。
+
+- **value**: `number | string`
+- **options**: `Intl.NumberFormatOptions & { locale?: LocalesValues }`
+  - 共通フィールド: `unit`（例: `"kilometer"`, `"byte"`）、`unitDisplay`（`"short" | "narrow" | "long"`）
+  - デフォルト: `unit: 'day'`、`unitDisplay: 'short'`、`useGrouping: false`
+
+例:
+
+```ts
+import { units } from "intlayer";
+
+units(5, { unit: "kilometer", unitDisplay: "long", locale: "en-GB" }); // "5 kilometers"
+units(1024, { unit: "byte", unitDisplay: "narrow" }); // "1,024B"（ロケール依存）
+```
+
+### `compact(value, options?)`
+
+数値をコンパクト表記（例: `1.2K`, `1M`）でフォーマットします。
+
+- **value**: `number | string`
+- **options**: `Intl.NumberFormatOptions & { locale?: LocalesValues }`（内部で `notation: 'compact'` を使用）
+
+例:
+
+```ts
+import { compact } from "intlayer";
+
+compact(1200); // "1.2K"
+compact("1000000", { locale: "fr", compactDisplay: "long" }); // "1 million"
+```
+
+## 注意事項
+
+- すべてのヘルパーは `string` 入力を受け付け、内部で数値や日付に変換されます。
+- ロケールは指定がなければ設定された `internationalization.defaultLocale` がデフォルトで使用されます。
+- これらのユーティリティは薄いラッパーであり、高度なフォーマットが必要な場合は標準の `Intl` オプションを直接渡してください。
+
+## エントリーポイントと再エクスポート（`@index.ts`）
+
+フォーマッターはコアパッケージに存在し、ランタイム間でのインポートを使いやすくするために上位パッケージから再エクスポートされています。
+
+- **options**: `Intl.NumberFormatOptions & { locale?: LocalesValues }`（内部で `notation: 'compact'` を使用）
+
+例:
+
+```ts
+import { compact } from "intlayer";
+
+compact(1200); // "1.2K"
+compact("1000000", { locale: "fr", compactDisplay: "long" }); // "1 million"
+```
+
+## 注意事項
+
+- すべてのヘルパーは `string` 入力を受け付け、内部で数値または日付に変換されます。
+- ロケールが指定されていない場合は、設定された `internationalization.defaultLocale` がデフォルトで使用されます。
+- これらのユーティリティは薄いラッパーであり、高度なフォーマットが必要な場合は標準の `Intl` オプションを直接渡してください。
+
+## エントリーポイントと再エクスポート（`@index.ts`）
+
+フォーマッターはコアパッケージに存在し、ランタイム間でのインポートを使いやすくするために上位パッケージから再エクスポートされています。
+
+例:
+
+```ts
+// アプリコード（推奨）
+import { number, currency, date, Intl } from "intlayer";
+```
+
+### React
+
+クライアントコンポーネント:
+
+```ts
+import { useNumber, useCurrency, useDate } from "react-intlayer/format";
+// または Next.js アプリの場合
+import { useNumber, useCurrency, useDate } from "next-intlayer/client/format";
+```
+
+サーバーコンポーネント（または React Server ランタイム）:
+
+```ts
+import { useNumber, useCurrency, useDate } from "intlayer/server/format";
+// または Next.js アプリの場合
+import { useNumber, useCurrency, useDate } from "next-intlayer/server/format";
+```
+
+> これらのフックは `IntlayerProvider` または `IntlayerServerProvider` からロケールを考慮します。
+
+## ドキュメント履歴
+
+| バージョン | 日付       | 変更内容                         |
+| ---------- | ---------- | -------------------------------- |
+| 5.8.0      | 2025-08-18 | フォーマッターのドキュメント追加 |