shirokuma-docs 0.1.0-alpha.1

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

@@ -0,0 +1,245 @@
+# Internationalization (i18n) Patterns
+
+Related: [code-quality.md](../criteria/code-quality.md)
+
+## Configuration
+
+### Routing Configuration
+
+```typescript
+// i18n/routing.ts
+import { defineRouting } from "next-intl/routing"
+
+export const routing = defineRouting({
+  locales: ["ja", "en"],
+  defaultLocale: "ja",
+  localePrefix: "never",  // Cookie-based, no URL prefix
+})
+```
+
+### Request Configuration
+
+```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
+
+### Required: setRequestLocale
+
+**CRITICAL**: Must call `setRequestLocale` at top of every Server Component page:
+
+```typescript
+import { getTranslations, setRequestLocale } from "next-intl/server"
+
+export default async function Page({ params }: { params: Promise<{ locale: string }> }) {
+  const { locale } = await params
+  setRequestLocale(locale)  // Required for static rendering!
+
+  const t = await getTranslations("common")
+  return <h1>{t("title")}</h1>
+}
+```
+
+**Error if missing**: Static rendering fails, translations work but slow.
+
+### Namespace-Based Translations
+
+```typescript
+// Get translations from specific namespace
+const t = await getTranslations("posts")
+t("title")  // messages.posts.title
+
+// Multiple namespaces
+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>
+}
+```
+
+### With 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>
+  )
+}
+```
+
+## Translation Files
+
+### Structure
+
+```json
+// messages/ja.json
+{
+  "common": {
+    "save": "保存",
+    "cancel": "キャンセル",
+    "logout": "ログアウト"
+  },
+  "posts": {
+    "title": "記事一覧",
+    "readMore": "続きを読む"
+  },
+  "auth": {
+    "loginError": "メールアドレスまたはパスワードが正しくありません"
+  }
+}
+```
+
+### Interpolation
+
+```json
+{
+  "postsCount": "{count}件の記事",
+  "greeting": "{name}さん、こんにちは"
+}
+```
+
+```typescript
+t("postsCount", { count: 10 })  // "10件の記事"
+t("greeting", { name: "田中" })  // "田中さん、こんにちは"
+```
+
+## Date Formatting
+
+```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"
+```
+
+## Japanese URL Slugs
+
+URL-encoded Japanese characters need decoding:
+
+```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)
+}
+```
+
+**Error if not decoded**: 404 for Japanese tag/category pages.
+
+## Testing Patterns
+
+### Mocking next-intl
+
+```typescript
+// jest.setup.ts
+jest.mock("next-intl", () => ({
+  useTranslations: () => (key: string) => key,
+  useLocale: () => "ja",
+}))
+```
+
+### Testing with Full 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>
+  )
+}
+```
+
+## Known Issues
+
+### Next.js 16 Compatibility (Issue #2064)
+
+- SSG builds fail because next-intl uses headers
+- Next.js 16 imposed stricter SSG restrictions
+- Check: https://github.com/amannn/next-intl/issues/2064
+
+### E2E Testing with i18n
+
+When testing with Playwright, handle both languages:
+
+```typescript
+// Match either English or Japanese text
+await expect(page.getByRole("button", { name: /Save|保存/i })).toBeVisible()
+await expect(page.getByText(/Invalid credentials|認証エラー/i)).toBeVisible()
+```
+
+## Anti-Patterns
+
+### Hardcoded Strings
+
+```typescript
+// Bad
+<button>Save</button>
+
+// Good
+const t = useTranslations("common")
+<button>{t("save")}</button>
+```
+
+### Missing setRequestLocale
+
+```typescript
+// Bad: Missing setRequestLocale
+export default async function Page({ params }) {
+  const { locale } = await params
+  const t = await getTranslations("common")  // Works but slow
+}
+
+// Good: With setRequestLocale
+export default async function Page({ params }) {
+  const { locale } = await params
+  setRequestLocale(locale)  // Required!
+  const t = await getTranslations("common")
+}
+```

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

@@ -0,0 +1,250 @@
+# JSDoc Documentation Patterns
+
+## Overview
+
+JSDoc patterns for TypeDoc API documentation generation.
+Server Actions, types, and interfaces should follow these patterns.
+
+## Required Tags by Function Type
+
+### Public 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
+}
+```
+
+### Internal Functions
+
+```typescript
+/**
+ * 内部関数の説明
+ *
+ * @internal
+ */
+function internalHelper(): void {
+  // implementation
+}
+```
+
+### Types and Interfaces
+
+```typescript
+/**
+ * 型の概要
+ *
+ * @typeParam T - ジェネリック型の説明
+ *
+ * @example
+ * ```typescript
+ * const result: PaginatedResult<Post> = {
+ *   items: posts,
+ *   total: 150,
+ *   page: 1
+ * }
+ * ```
+ *
+ * @category 型定義
+ */
+export interface PaginatedResult<T> {
+  /** 現在のページのアイテム配列 */
+  items: T[]
+  /** 全アイテム数 */
+  total: number
+}
+```
+
+## Tag Reference
+
+| Tag | Required | Usage |
+|-----|----------|-------|
+| `@param` | Yes (if params) | パラメータの説明 |
+| `@returns` | Yes (if returns) | 戻り値の説明 |
+| `@example` | Recommended | 使用例（コードブロック付き） |
+| `@see` | Recommended | 関連する関数・型への参照 |
+| `@throws` | If applicable | スローする可能性のあるエラー |
+| `@category` | Recommended | TypeDocでのカテゴリ分類 |
+| `@internal` | If internal | 内部関数（ドキュメントから除外） |
+| `@typeParam` | If generic | ジェネリック型の説明 |
+
+## Category Standards
+
+Use consistent category names:
+
+| Category | Used For |
+|----------|----------|
+| `投稿取得` | Post read operations |
+| `投稿操作` | Post write operations |
+| `カテゴリ取得` | Category read operations |
+| `カテゴリ操作` | Category write operations |
+| `タグ取得` | Tag read operations |
+| `タグ操作` | Tag write operations |
+| `コメント取得` | Comment read operations |
+| `コメント操作` | Comment write operations |
+| `認証` | Authentication operations |
+| `型定義` | Types and interfaces |
+
+## Good Examples
+
+### Server Action with Full Documentation
+
+```typescript
+/**
+ * ページネーション付きで投稿を取得
+ *
+ * 管理画面の投稿一覧ページで使用。指定したページの投稿と
+ * ページネーション情報（総数、総ページ数など）を返します。
+ *
+ * @param page - ページ番号（1から開始、デフォルト: 1）
+ * @param pageSize - 1ページあたりの表示件数（デフォルト: 10）
+ * @returns ページネーション結果（items, total, page, pageSize, totalPages）
+ *
+ * @example
+ * ```typescript
+ * // 1ページ目を10件で取得
+ * 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
+}
+```
+
+### Interface with Property Documentation
+
+```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 }[]
+}
+```
+
+## Bad Examples
+
+### Missing Required Tags
+
+```typescript
+// BAD: No @param, @returns, @example
+/**
+ * Get posts
+ */
+export async function getPosts(): Promise<Post[]> {
+  // implementation
+}
+```
+
+### Vague Description
+
+```typescript
+// BAD: Description doesn't explain what the function does
+/**
+ * Handles posts
+ *
+ * @param id - id
+ * @returns result
+ */
+export async function handlePost(id: string): Promise<Result> {
+  // implementation
+}
+```
+
+### Missing Property Documentation
+
+```typescript
+// BAD: No documentation on properties
+export interface UserData {
+  id: string
+  name: string
+  email: string
+}
+```
+
+## Review Checklist
+
+### Public Functions
+- [ ] Has summary (first line)
+- [ ] Has detailed description (if complex)
+- [ ] All parameters documented with `@param`
+- [ ] Return value documented with `@returns`
+- [ ] Has `@example` with code block
+- [ ] Has `@category` for TypeDoc grouping
+- [ ] Has `@see` for related functions
+- [ ] Has `@throws` if errors can be thrown
+
+### Types/Interfaces
+- [ ] Has type summary
+- [ ] Has `@typeParam` for generics
+- [ ] Has `@example` showing usage
+- [ ] Has `@category` for TypeDoc grouping
+- [ ] All properties have inline `/** comment */`
+
+### Internal Functions
+- [ ] Has `@internal` tag
+- [ ] Has brief description
+
+## TypeDoc Configuration
+
+Reference: `typedoc.json`
+
+```json
+{
+  "excludePrivate": true,
+  "excludeProtected": true,
+  "excludeInternal": true,
+  "categorizeByGroup": true,
+  "categoryOrder": ["Server Actions", "Database", "*"]
+}
+```
+
+- `@internal` tagged functions are excluded from docs
+- `@category` groups functions in navigation
+- Property-level `/** comments */` are included