Yutaka Kurosaki
01fb8b9fcf
Documents the data model (1 doc + document_translations table), service layer changes, routing/editor UX, wiki-link resolution order, search, and migration plan. Article URLs stay locale-independent; display falls back to each document's default_locale when the requested locale lacks a translation. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
276 lines
15 KiB
Markdown
276 lines
15 KiB
Markdown
# 記事の多言語対応 + デフォルト言語フォールバック
|
||
|
||
- **Date:** 2026-05-10
|
||
- **Branch:** `feature/article-i18n`（`main` から分岐）
|
||
- **Status:** Design approved, ready for implementation plan
|
||
|
||
## 背景
|
||
|
||
UI言語切り替えは16言語対応済み（`SetLocale` ミドルウェア + `users.locale` カラム + セッション/Cookie）。
|
||
一方、記事本体（`documents` テーブル）は単一言語のまま：1ドキュメント = 1行で `title`/`content`/`rendered_html` を直接保持し、locale非対応。
|
||
|
||
本設計は、記事自体を多言語化し、ユーザーのUI言語に応じた翻訳を提示する。翻訳が無ければ「その記事の原語版」へフォールバックする。
|
||
|
||
## 決定事項サマリ
|
||
|
||
| 論点 | 決定 |
|
||
|---|---|
|
||
| 翻訳のデータモデル | 1記事 + `document_translations` 子テーブル |
|
||
| デフォルト言語 | 記事ごとに `documents.default_locale` を持つ |
|
||
| URL | デフォルト言語のslug固定（言語非依存） |
|
||
| 表示title | 現在locale → default_locale でフォールバック |
|
||
| 編集UX | 1記事の編集画面に言語タブ |
|
||
| `[[wiki-link]]` 解決 | 全言語のtitleを対象、現在locale優先の決定論的順序 |
|
||
| 検索 | 全言語のtitle/contentを対象、表示titleは現在locale |
|
||
| マイグレーション | 既存記事は `config('app.locale')` を `default_locale` として移行 |
|
||
| フォールバック表示 | 上部バナー + 「翻訳を追加」ボタン |
|
||
|
||
## Section 1: データモデル
|
||
|
||
### `documents` テーブル（変更）
|
||
|
||
| 操作 | カラム | 備考 |
|
||
|---|---|---|
|
||
| 追加 | `default_locale` VARCHAR(10) NOT NULL | フォールバック先となる原語 |
|
||
| 削除 | `title` | `document_translations` へ移管 |
|
||
| 削除 | `content` | 同上 |
|
||
| 削除 | `rendered_html` | 同上 |
|
||
| 維持 | `path`, `slug`, `frontmatter`, `file_size`, `file_hash`, `file_modified_at`, `created_by`, `updated_by`, timestamps, `softDeletes` | |
|
||
|
||
`path`/`slug` は引き続き「default_locale のtitle」から生成。タイトル変更で再生成される既存ロジックも default_locale のtitleに連動。
|
||
|
||
### `document_translations` テーブル（新規）
|
||
|
||
```
|
||
id BIGINT PK
|
||
document_id FK → documents (cascade delete)
|
||
locale VARCHAR(10)
|
||
title VARCHAR(255)
|
||
content TEXT
|
||
rendered_html TEXT NULLABLE
|
||
created_by FK → users (nullOnDelete)
|
||
updated_by FK → users (nullOnDelete)
|
||
created_at, updated_at
|
||
|
||
UNIQUE (document_id, locale)
|
||
INDEX (locale, title) -- wiki-link / QuickSwitcher 用
|
||
FULLTEXT (title, content) WITH PARSER ngram -- MySQL のみ（既存と同条件）
|
||
```
|
||
|
||
- `(locale, title)` には**unique制約は付けない**。既存 `documents.title` も unique でないため挙動互換性を保つ。代わりに wiki-link 解決順序を決定論にする。
|
||
- SQLite（テスト環境）では FULLTEXT インデックス作成をスキップ（既存マイグレーションと同じ条件分岐）。
|
||
|
||
### マイグレーション手順
|
||
|
||
1. `documents.default_locale` カラム追加（デフォルト値 `config('app.locale')`、nullable=false）
|
||
2. `document_translations` テーブル作成
|
||
3. データ移行：既存各 `documents` 行から `(title, content, rendered_html, created_by, updated_by)` を `document_translations` に複製、`locale = config('app.locale')` をセット
|
||
4. `documents` テーブルの旧FULLTEXTインデックス（`documents_search_index`）を削除
|
||
5. `documents.title`, `documents.content`, `documents.rendered_html` カラムを削除
|
||
|
||
`down()` は対称的に逆順で復元するが、データ復元は best-effort（複数translation存在時はdefault_localeのものを採用）。
|
||
|
||
## Section 2: モデル & サービス層
|
||
|
||
### `Document` モデル
|
||
|
||
- `title`/`content`/`rendered_html` をfillable/直接プロパティから削除
|
||
- 新リレーション
|
||
- `translations(): HasMany` → `DocumentTranslation`
|
||
- `defaultTranslation(): HasOne` → `where('locale', $this->default_locale)`
|
||
- アクセサ（**現在 `App::getLocale()` のtranslation → 無ければdefault_localeのtranslation**）
|
||
- `getTitleAttribute(): string`
|
||
- `getContentAttribute(): string`
|
||
- `getRenderedHtmlAttribute(): ?string`
|
||
- 新メソッド
|
||
- `translationFor(string $locale, bool $fallback = true): ?DocumentTranslation`
|
||
- `isFallback(string $requestedLocale): bool` — バナー判定用
|
||
- `availableLocales(): array` — タブ生成用、translation存在のlocale一覧
|
||
|
||
### `DocumentTranslation` モデル（新規）
|
||
|
||
```php
|
||
fillable: [document_id, locale, title, content, rendered_html, created_by, updated_by]
|
||
casts: timestamps
|
||
relations: document(): BelongsTo, creator(), updater()
|
||
scope: scopeSearch(Builder, string) -- MATCH(title, content) AGAINST(?)
|
||
static: renderMarkdown(string): string -- Document から移管（純粋関数）
|
||
```
|
||
|
||
### `DocumentService` 改修
|
||
|
||
| メソッド | 変更内容 |
|
||
|---|---|
|
||
| `createDocument($title, $content, $userId, $locale = null)` | `$locale` 未指定なら `App::getLocale()`。document を作成し `default_locale = $locale`、translationを1件作成。path/slug は title から生成 |
|
||
| `updateDocument(Document $doc, $title, $content, $userId, $locale)` | 指定 `$locale` のtranslationをupsert。`$locale === default_locale` のときだけ path/slug 再生成 |
|
||
| `addTranslation(Document $doc, $locale, $title, $content, $userId): DocumentTranslation` | 新言語のtranslation追加。重複locale時は422 |
|
||
| `deleteTranslation(Document $doc, string $locale): void` | default_locale の翻訳は削除拒否（例外） |
|
||
| `setDefaultLocale(Document $doc, string $locale): Document` | `default_locale` 切り替え。新しいdefault_localeのtranslationが存在しない場合422。切替後 path/slug を新default_localeのtitleから再生成 |
|
||
| `findByTitle($title, $locale = null): ?Document` | locale指定優先。後述の解決順序を実装 |
|
||
| `search(string $query, int $limit = 20)` | `DocumentTranslation::search()` ベース、結果documentをdistinct化 |
|
||
| `getDirectoryTree()` | path/階層構造はdocumentレベルのまま、表示titleはアクセサ経由で現在locale + フォールバック |
|
||
|
||
### `WikiLinkResolver`（新規 `app/Services/WikiLinkResolver.php`）
|
||
|
||
`processLinks()` と `syncLinks()` から共通利用される解決ロジック：
|
||
|
||
```
|
||
resolve(string $linkText, string $currentLocale): ?Document
|
||
1. translations WHERE locale = $currentLocale AND title = $linkText
|
||
2. translations WHERE locale = document.default_locale AND title = $linkText
|
||
3. translations WHERE title = $linkText
|
||
ORDER BY document_id ASC LIMIT 1
|
||
4. documents WHERE slug = SlugHelper::generate($linkText)
|
||
5. null
|
||
```
|
||
|
||
- `Document::syncLinks()` と `Document::processLinks()` はResolver利用に書き換え
|
||
- `processLinks()` のリンク**表示ラベル**は原文のまま（例: 英語本文中の `[[Getting Started]]` はja表示時もラベル「Getting Started」）。クリック後の遷移先記事は現在localeで表示される
|
||
- 既存の `DocumentLink` テーブルはスキーマ無変更（`target_title` を保存しているだけなのでlocale非依存で運用可能）
|
||
|
||
## Section 3: ルーティング & コントローラ層
|
||
|
||
### 既存ルート（変更なし）
|
||
|
||
- `GET /documents/{document}` → slug一致でdocumentバインド
|
||
- `GET /documents/{document}/edit`
|
||
- `GET /documents/create`
|
||
|
||
URLは言語非依存。表示言語は `SetLocale` ミドルウェアが解決した `App::getLocale()` に従う。
|
||
|
||
### `Document::resolveRouteBinding()`
|
||
|
||
slugは `documents` テーブル直下のため既存ロジックそのまま。
|
||
翻訳title（例: `はじめに`）でURLを直接叩いた場合は404のまま（検索/QuickSwitcher経由で見つける想定）。
|
||
|
||
### 新規ルート: 翻訳の管理
|
||
|
||
| メソッド | URL | 名前 | 機能 |
|
||
|---|---|---|---|
|
||
| GET | `/documents/{document}/translations/{locale}/edit` | `documents.translations.edit` | 既存翻訳の編集（`DocumentEditor` を再利用） |
|
||
| POST | `/documents/{document}/translations` | `documents.translations.store` | 新言語追加 |
|
||
| DELETE | `/documents/{document}/translations/{locale}` | `documents.translations.destroy` | 翻訳削除（default_locale 不可） |
|
||
|
||
- `{locale}` は `SetLocale::SUPPORTED_LOCALES` のキーで route constraint
|
||
- すべて `auth` + `can:update,document` ミドルウェア配下
|
||
|
||
### `/` ルート
|
||
|
||
`slug = home` の document を探してリダイレクト（既存通り、slugは言語非依存のため変更不要）。
|
||
|
||
## Section 4: Livewire コンポーネント & ビュー
|
||
|
||
### `DocumentViewer`（改修）
|
||
|
||
```php
|
||
public Document $document;
|
||
public string $viewLocale; // 実際に表示中のlocale（フォールバック後）
|
||
public bool $isFallback; // バナー表示判定
|
||
public string $renderedContent; // wiki-link処理済みHTML
|
||
public $backlinks;
|
||
```
|
||
|
||
`mount()` フロー:
|
||
1. `$current = App::getLocale()`
|
||
2. `$translation = $document->translationFor($current, fallback: true)`
|
||
3. `$this->viewLocale = $translation->locale`
|
||
4. `$this->isFallback = ($current !== $translation->locale)`
|
||
5. `WikiLinkResolver` で `$translation->rendered_html` 内のwiki-linkを現在locale基準で再解決
|
||
|
||
ビュー `livewire/document-viewer.blade.php`:
|
||
- 上部にフォールバックバナー（`$isFallback === true` のみ）
|
||
- 文言は `lang/{locale}/messages.php` に追加（例: `documents.fallback_notice`、`documents.add_translation`）
|
||
- 「翻訳を追加」ボタン → `documents.translations.store` への小フォーム（locale = 現在UI locale）
|
||
- バックリンク表示titleは `$backlink->title` アクセサ経由（自動でフォールバック）
|
||
|
||
### `DocumentEditor`（改修）
|
||
|
||
```php
|
||
public ?Document $document; // 既存編集時、新規作成時はnull
|
||
public string $editingLocale; // 現在編集中のタブ
|
||
public string $title; // editingLocale の title
|
||
public string $content; // editingLocale の content
|
||
public array $availableLocales; // この記事で既に翻訳がある locale 一覧
|
||
public bool $isNewLocale; // 既存翻訳の編集 or 新規追加
|
||
```
|
||
|
||
メソッド:
|
||
- `switchTab(string $locale)` — 未保存変更があれば確認ダイアログ、translation取得 or 空フォーム
|
||
- `save()` — 既存ならupdate、新規ならaddTranslation
|
||
- `delete()` — 翻訳削除（default_locale以外）
|
||
- `setAsDefault(string $locale)` — default_locale変更（path/slug再生成）
|
||
|
||
ビュー `livewire/document-editor.blade.php`:
|
||
- 上部にタブバー: `[JA*] [EN] [zh-CN] [+ 翻訳を追加 ▾]`
|
||
- `*` は default_locale 印
|
||
- `+` ドロップダウンで未追加の `SUPPORTED_LOCALES` を選択可能
|
||
- 既存のEasyMDE設定はそのまま流用、`wire:model` の単一入力構造を維持
|
||
- default_locale変更UI（タブの隣にメニュー or 「この言語をデフォルトにする」ボタン）
|
||
|
||
### `SidebarTree`（軽微改修）
|
||
|
||
- `getDirectoryTree()` の戻り値内 `name`（path basename）はpathベースのまま
|
||
- ファイル名表示は `$document->title`（アクセサ経由）に切り替え
|
||
- treeのキャッシュキー（もしあれば）に `App::getLocale()` を含めて、locale切替で再構築
|
||
|
||
### `QuickSwitcher`（改修）
|
||
|
||
- 検索クエリを `DocumentTranslation::search()` に投げ、結果documentをdistinct化
|
||
- 表示行は `$doc->title`（アクセサ）+ ヒットしたtranslationが現在locale以外なら小さなlocaleバッジ
|
||
|
||
## Section 5: テスト計画 & 受け入れ基準
|
||
|
||
### ユニットテスト（追加）
|
||
|
||
| ファイル | 検証内容 |
|
||
|---|---|
|
||
| `tests/Unit/Models/DocumentTest.php` | `title`/`content`/`rendered_html` アクセサが現在localeを返す／無ければdefault_localeにフォールバック／`isFallback()` 真偽／`availableLocales()` |
|
||
| `tests/Unit/Models/DocumentTranslationTest.php` | `(document_id, locale)` unique／cascade delete／`renderMarkdown()` |
|
||
| `tests/Unit/Services/WikiLinkResolverTest.php` | 解決順序5段階すべて／同名タイトル衝突時の決定論性／slug fallback／nullケース |
|
||
| `tests/Unit/Services/DocumentServiceTest.php` | `createDocument` がtranslationを1件生成／`updateDocument` がdefault_locale時のみpath再生成／`addTranslation`／`deleteTranslation`（default_locale削除拒否）／`setDefaultLocale`（未存在translation時422 + path再生成）／`search` のdistinct化 |
|
||
|
||
### フィーチャーテスト（追加）
|
||
|
||
| ファイル | 検証内容 |
|
||
|---|---|
|
||
| `tests/Feature/DocumentI18nTest.php` | 現在locale=ja で英語のみの記事を表示→英語版が表示されバナーが出る／ja版を追加後はバナーなし／QuickSwitcherで日本語クエリ・英語クエリどちらも同記事ヒット |
|
||
| `tests/Feature/DocumentTranslationCrudTest.php` | 翻訳追加POST／編集GET/PATCH／削除DELETE（default_localeは422）／非権限ユーザは403 |
|
||
| `tests/Feature/DocumentMigrationTest.php` | マイグレーション前の擬似データ→migrate実行→translationsへ正しく移行／documentsの旧カラムが消去 |
|
||
|
||
### 既存テストの修正範囲
|
||
|
||
- `DocumentService` を呼ぶ既存テストはfactoryで `default_locale` 指定が必要
|
||
- `Document::factory()` は `DocumentTranslationFactory` と連動
|
||
- 既存の `processLinks` / `syncLinks` テストは `WikiLinkResolver` 経由に書き換え
|
||
|
||
### 受け入れ基準（DoD）
|
||
|
||
1. UI言語をjaにして英語のみ記事を開く → 英語コンテンツが表示され、上部に日本語バナー＋「翻訳を追加」ボタンが出る
|
||
2. 「翻訳を追加」→ 編集画面でja版を作成・保存 → 同URLを再表示 → ja版がバナーなしで表示
|
||
3. `[[Getting Started]]` と `[[はじめに]]` の両方が同一記事へリンクする
|
||
4. QuickSwitcherで「はじめに」「Getting Started」どちらでも同記事がヒットする
|
||
5. 編集画面の言語タブを切り替えて、各言語のtitle/contentを独立に編集・保存できる
|
||
6. default_locale設定の翻訳は削除できない（UIで削除ボタン非表示＋バックエンドで422）
|
||
7. 既存の `composer test` がすべて緑
|
||
8. マイグレーション後、既存記事すべてが `default_locale = config('app.locale')` で正しく翻訳化されている
|
||
|
||
## ブランチ & コミット計画
|
||
|
||
- ブランチ: `feature/article-i18n` を **`main` から分岐**（`feature/media-manager` ではない）
|
||
- コミット粒度の目安（1 PR想定で7コミット）：
|
||
1. マイグレーション（`document_translations` 作成 + 既存データ移行 + 旧カラム削除）
|
||
2. `DocumentTranslation` モデル + factory
|
||
3. `Document` モデルアクセサ/リレーション改修
|
||
4. `WikiLinkResolver` + `DocumentService` 改修
|
||
5. ルート + 翻訳CRUDコントローラ
|
||
6. `DocumentViewer` + バナー + lang追加
|
||
7. `DocumentEditor` タブUI + `SidebarTree`/`QuickSwitcher` 調整
|
||
|
||
## スコープ外（YAGNI）
|
||
|
||
- 翻訳の自動生成（DeepL等の外部API連携）
|
||
- 翻訳の進捗ダッシュボード（カバレッジ表示）
|
||
- 言語ごとの別URL（`/ja/documents/...`）
|
||
- title翻訳に応じたslugの言語別生成
|
||
- RTL言語サポート
|