shirokuma-docs 0.1.0-alpha.1

package/plugin/shirokuma-skills-ja/skills/reviewing-on-issue/patterns/i18n.md

@@ -0,0 +1,242 @@
+# 国際化（i18n）パターン
+
+関連: [code-quality.md](../criteria/code-quality.md)
+
+## 設定
+
+### ルーティング設定
+
+```typescript
+// i18n/routing.ts
+import { defineRouting } from "next-intl/routing"
+
+export const routing = defineRouting({
+  locales: ["ja", "en"],
+  defaultLocale: "ja",
+  localePrefix: "never",  // Cookie ベース、URL プレフィックスなし
+})
+```
+
+### リクエスト設定
+
+```typescript
+// i18n/request.ts
+import { getRequestConfig } from "next-intl/server"
+import { routing } from "./routing"
+
+export default getRequestConfig(async ({ requestLocale }) => {
+  let locale = await requestLocale
+  if (!locale || !routing.locales.includes(locale as any)) {
+    locale = routing.defaultLocale
+  }
+
+  return {
+    locale,
+    messages: (await import(`../messages/${locale}.json`)).default,
+  }
+})
+```
+
+## Server Components
+
+### 必須: setRequestLocale
+
+**重要**: すべての Server Component ページで `setRequestLocale` を呼ぶ必要がある:
+
+```typescript
+import { getTranslations, setRequestLocale } from "next-intl/server"
+
+export default async function Page({ params }: { params: Promise<{ locale: string }> }) {
+  const { locale } = await params
+  setRequestLocale(locale)  // 静的レンダリングに必須!
+
+  const t = await getTranslations("common")
+  return <h1>{t("title")}</h1>
+}
+```
+
+**未指定の場合**: 静的レンダリングが失敗し、翻訳は動作するが低速。
+
+### 名前空間ベースの翻訳
+
+```typescript
+const t = await getTranslations("posts")
+t("title")  // messages.posts.title
+
+// 複数名前空間
+const [tCommon, tPosts] = await Promise.all([
+  getTranslations("common"),
+  getTranslations("posts"),
+])
+```
+
+## Client Components
+
+```typescript
+"use client"
+import { useTranslations, useLocale } from "next-intl"
+
+export function MyComponent() {
+  const t = useTranslations("namespace")
+  const locale = useLocale()
+
+  return <button>{t("submit")}</button>
+}
+```
+
+### Provider 付き
+
+```typescript
+import { NextIntlClientProvider } from "next-intl"
+
+function renderWithProviders(ui: React.ReactElement, locale = "en") {
+  const messages = { common: { save: "Save" } }
+  return render(
+    <NextIntlClientProvider locale={locale} messages={messages}>
+      {ui}
+    </NextIntlClientProvider>
+  )
+}
+```
+
+## 翻訳ファイル
+
+### 構造
+
+```json
+// messages/ja.json
+{
+  "common": {
+    "save": "保存",
+    "cancel": "キャンセル",
+    "logout": "ログアウト"
+  },
+  "posts": {
+    "title": "記事一覧",
+    "readMore": "続きを読む"
+  },
+  "auth": {
+    "loginError": "メールアドレスまたはパスワードが正しくありません"
+  }
+}
+```
+
+### 補間
+
+```json
+{
+  "postsCount": "{count}件の記事",
+  "greeting": "{name}さん、こんにちは"
+}
+```
+
+```typescript
+t("postsCount", { count: 10 })  // "10件の記事"
+t("greeting", { name: "田中" })  // "田中さん、こんにちは"
+```
+
+## 日付フォーマット
+
+```typescript
+const dateLocale = locale === "ja" ? "ja-JP" : "en-US"
+
+post.publishedAt.toLocaleDateString(dateLocale, {
+  year: "numeric",
+  month: "long",
+  day: "numeric",
+})
+// Japanese: "2025年11月28日"
+// English: "November 28, 2025"
+```
+
+## 日本語 URL スラッグ
+
+URL エンコードされた日本語文字はデコードが必要:
+
+```typescript
+// URL: /tag/%E6%97%A5%E6%9C%AC%E8%AA%9E
+export default async function TagPage({ params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params
+  const decodedSlug = decodeURIComponent(slug)  // "日本語"
+  const tag = await getTagBySlug(decodedSlug)
+}
+```
+
+**未デコードの場合**: 日本語タグ/カテゴリページで 404。
+
+## テストパターン
+
+### next-intl のモック
+
+```typescript
+// jest.setup.ts
+jest.mock("next-intl", () => ({
+  useTranslations: () => (key: string) => key,
+  useLocale: () => "ja",
+}))
+```
+
+### フル i18n でのテスト
+
+```typescript
+import { NextIntlClientProvider } from "next-intl"
+
+const messages = {
+  common: { save: "Save" },
+  features: { title: "Features" },
+}
+
+function renderWithIntl(ui: React.ReactElement) {
+  return render(
+    <NextIntlClientProvider locale="en" messages={messages}>
+      {ui}
+    </NextIntlClientProvider>
+  )
+}
+```
+
+## 既知の問題
+
+### Next.js 16 互換性 (Issue #2064)
+
+- next-intl が headers を使用するため SSG ビルドが失敗
+- Next.js 16 で SSG 制限が厳格化
+- 確認: https://github.com/amannn/next-intl/issues/2064
+
+### E2E テストでの i18n
+
+```typescript
+// 日英両方のテキストにマッチ
+await expect(page.getByRole("button", { name: /Save|保存/i })).toBeVisible()
+await expect(page.getByText(/Invalid credentials|認証エラー/i)).toBeVisible()
+```
+
+## アンチパターン
+
+### ハードコード文字列
+
+```typescript
+// Bad
+<button>Save</button>
+
+// Good
+const t = useTranslations("common")
+<button>{t("save")}</button>
+```
+
+### setRequestLocale の欠落
+
+```typescript
+// Bad: setRequestLocale なし
+export default async function Page({ params }) {
+  const { locale } = await params
+  const t = await getTranslations("common")  // 動作するが低速
+}
+
+// Good: setRequestLocale あり
+export default async function Page({ params }) {
+  const { locale } = await params
+  setRequestLocale(locale)  // 必須!
+  const t = await getTranslations("common")
+}
+```

package/plugin/shirokuma-skills-ja/skills/reviewing-on-issue/patterns/jsdoc.md

@@ -0,0 +1,247 @@
+# JSDoc ドキュメントパターン
+
+## 概要
+
+TypeDoc API ドキュメント生成のための JSDoc パターン。
+Server Actions、型、インターフェースはこのパターンに従う。
+
+## 関数タイプ別の必須タグ
+
+### 公開 Server Actions
+
+```typescript
+/**
+ * 関数の概要（1行目）
+ *
+ * 詳細な説明（2行目以降）。
+ * 処理フローや注意点を記載。
+ *
+ * @param paramName - パラメータの説明
+ * @returns 戻り値の説明
+ *
+ * @example
+ * ```typescript
+ * const result = await myFunction(params)
+ * ```
+ *
+ * @see {@link relatedFunction} - 関連する関数
+ * @throws {Error} エラー条件の説明
+ *
+ * @category カテゴリ名
+ */
+export async function myFunction(paramName: string): Promise<Result> {
+  // implementation
+}
+```
+
+### 内部関数
+
+```typescript
+/**
+ * 内部関数の説明
+ *
+ * @internal
+ */
+function internalHelper(): void {
+  // implementation
+}
+```
+
+### 型とインターフェース
+
+```typescript
+/**
+ * 型の概要
+ *
+ * @typeParam T - ジェネリック型の説明
+ *
+ * @example
+ * ```typescript
+ * const result: PaginatedResult<Post> = {
+ *   items: posts,
+ *   total: 150,
+ *   page: 1
+ * }
+ * ```
+ *
+ * @category 型定義
+ */
+export interface PaginatedResult<T> {
+  /** 現在のページのアイテム配列 */
+  items: T[]
+  /** 全アイテム数 */
+  total: number
+}
+```
+
+## タグリファレンス
+
+| タグ | 必須 | 用途 |
+|-----|------|------|
+| `@param` | パラメータがあれば必須 | パラメータの説明 |
+| `@returns` | 戻り値があれば必須 | 戻り値の説明 |
+| `@example` | 推奨 | 使用例（コードブロック付き） |
+| `@see` | 推奨 | 関連する関数・型への参照 |
+| `@throws` | 該当時 | スローする可能性のあるエラー |
+| `@category` | 推奨 | TypeDoc でのカテゴリ分類 |
+| `@internal` | 内部関数の場合 | ドキュメントから除外 |
+| `@typeParam` | ジェネリクスの場合 | ジェネリック型の説明 |
+
+## カテゴリ標準
+
+一貫したカテゴリ名を使用:
+
+| カテゴリ | 対象 |
+|----------|------|
+| `投稿取得` | 投稿の読み取り操作 |
+| `投稿操作` | 投稿の書き込み操作 |
+| `カテゴリ取得` | カテゴリの読み取り操作 |
+| `カテゴリ操作` | カテゴリの書き込み操作 |
+| `タグ取得` | タグの読み取り操作 |
+| `タグ操作` | タグの書き込み操作 |
+| `コメント取得` | コメントの読み取り操作 |
+| `コメント操作` | コメントの書き込み操作 |
+| `認証` | 認証操作 |
+| `型定義` | 型とインターフェース |
+
+## 良い例
+
+### フルドキュメント付き Server Action
+
+```typescript
+/**
+ * ページネーション付きで投稿を取得
+ *
+ * 管理画面の投稿一覧ページで使用。指定したページの投稿と
+ * ページネーション情報（総数、総ページ数など）を返します。
+ *
+ * @param page - ページ番号（1から開始、デフォルト: 1）
+ * @param pageSize - 1ページあたりの表示件数（デフォルト: 10）
+ * @returns ページネーション結果（items, total, page, pageSize, totalPages）
+ *
+ * @example
+ * ```typescript
+ * const result = await getPaginatedPosts(1, 10)
+ * console.log(`全${result.total}件中 ${result.items.length}件を表示`)
+ * ```
+ *
+ * @see {@link getPosts} - 全件取得する場合
+ * @see {@link PaginatedResult} - 戻り値の型定義
+ *
+ * @category 投稿取得
+ */
+export async function getPaginatedPosts(
+  page: number = 1,
+  pageSize: number = 10
+): Promise<PaginatedResult<Post>> {
+  // implementation
+}
+```
+
+### プロパティドキュメント付きインターフェース
+
+```typescript
+/**
+ * カテゴリーとタグを含む投稿型
+ *
+ * 投稿の詳細表示で使用される拡張型。
+ * 基本の Post 型に加えて、関連するカテゴリーとタグの情報を含む。
+ *
+ * @example
+ * ```typescript
+ * const post: PostWithRelations = {
+ *   id: "123",
+ *   title: "記事タイトル",
+ *   category: { id: "cat-1", name: "技術", slug: "tech" },
+ *   tags: [{ id: "tag-1", name: "TypeScript", slug: "typescript" }]
+ * }
+ * ```
+ *
+ * @category 型定義
+ */
+export interface PostWithRelations extends Post {
+  /** 投稿のカテゴリー（未分類の場合はnull） */
+  category: { id: string; name: string; slug: string } | null
+  /** 投稿に紐づくタグの配列 */
+  tags: { id: string; name: string; slug: string }[]
+}
+```
+
+## 悪い例
+
+### 必須タグの欠落
+
+```typescript
+// BAD: @param, @returns, @example なし
+/**
+ * Get posts
+ */
+export async function getPosts(): Promise<Post[]> {
+  // implementation
+}
+```
+
+### 曖昧な説明
+
+```typescript
+// BAD: 関数が何をするか説明していない
+/**
+ * Handles posts
+ *
+ * @param id - id
+ * @returns result
+ */
+export async function handlePost(id: string): Promise<Result> {
+  // implementation
+}
+```
+
+### プロパティドキュメントの欠落
+
+```typescript
+// BAD: プロパティにドキュメントなし
+export interface UserData {
+  id: string
+  name: string
+  email: string
+}
+```
+
+## レビューチェックリスト
+
+### 公開関数
+- [ ] サマリー（1行目）あり
+- [ ] 詳細説明あり（複雑な場合）
+- [ ] すべてのパラメータに `@param` あり
+- [ ] 戻り値に `@returns` あり
+- [ ] コードブロック付き `@example` あり
+- [ ] TypeDoc 分類用の `@category` あり
+- [ ] 関連関数への `@see` あり
+- [ ] エラー発生時の `@throws` あり
+
+### 型/インターフェース
+- [ ] 型サマリーあり
+- [ ] ジェネリクスに `@typeParam` あり
+- [ ] 使用例の `@example` あり
+- [ ] TypeDoc 分類用の `@category` あり
+- [ ] すべてのプロパティにインライン `/** コメント */` あり
+
+### 内部関数
+- [ ] `@internal` タグあり
+- [ ] 簡潔な説明あり
+
+## TypeDoc 設定
+
+```json
+{
+  "excludePrivate": true,
+  "excludeProtected": true,
+  "excludeInternal": true,
+  "categorizeByGroup": true,
+  "categoryOrder": ["Server Actions", "Database", "*"]
+}
+```
+
+- `@internal` タグ付き関数はドキュメントから除外
+- `@category` でナビゲーション内をグループ化
+- プロパティレベルの `/** コメント */` も含まれる