logo hsb.horse

Architecture Decision Record

個別ツール追加の実装方針

ツール追加時のルーティング、feature責務、i18n配置ルールを定義する。

採用 #tools #architecture #routing #i18n

他の言語

英語 ポルトガル語

個別ツール追加の実装方針

Decision

  • 個別ツールのページエントリは src/pages/tools/[category]/[tool-slug]/index.astro を基本構造として採用する。
  • 多言語URLが必要な場合は、既存i18n方針に合わせて src/pages/[lang]/tools/[category]/[tool-slug]/index.astro も同構造で用意する。
  • ページファイルは薄い接着層にし、実装本体は src/features/tools/[tool-slug]/ に集約する。
  • src/features/tools/ 直下には共通責務のみを置く。対象は一覧データ取得、slug/categoryユーティリティ、共通UI、共通型とする。
  • ツール固有文言は src/features/tools/[tool-slug]/i18n/{lang}.json で管理する。
  • src/i18n はサイト全体で共有する文言のみを管理する。
  • 同一文言を2つ以上のツール、またはツール外ページでも再利用する場合のみ src/i18n へ昇格する。
  • 各ツールページは SoftwareApplication のJSON-LDを必ず出力する。
  • 各ツールページは可視パンくずナビゲーションを必ず設置し、BreadcrumbList のJSON-LDも必ず出力する。

Context

ツール一覧は既に共通管理されている一方、個別ツールはUIとロジックが独立しやすい。追加時の実装場所と言語ファイルの置き場所を明確にしないと、src/i18n の肥大化またはツール間の責務混在が起きやすい状態だった。

Options

  • Option A: ツール文言をすべて src/i18n に集約する。
  • Option B: ツール文言をすべて各ツール配下だけで管理する。
  • Option C: 原則ツール配下で管理し、再利用が発生した文言のみ src/i18n に集約するハイブリッド運用にする（採用）。

Rationale

  • 実装と文言を同じ feature に寄せることで、変更影響範囲を局所化できる。
  • グローバルi18nをサイト共通文言に限定することで、肥大化とマージ競合を抑制できる。
  • 昇格ルールを設けることで、過度な分散と過度な集中の両方を避けられる。
  • ページ層を薄く保つことで、既存の pages/features 分離方針と整合する。

Consequences

  • 新規ツール追加時は、src/features/tools/[tool-slug]/ に実装と i18n/{lang}.json をセットで追加する。
  • src/pages/.../tools/... のファイルは、ルーティングとprops受け渡しを主責務とする。
  • 一覧カード向けメタ情報（title / description）は、既存ADRに従って docs/tools/*.yaml で管理する。
  • 共通文言の昇格基準を運用ルールとしてレビュー時に確認する。
  • ツールページの受け入れ条件に「SoftwareApplication 構造化データ」「可視パンくず + BreadcrumbList」を追加する。