【OSSでWiki構築】連載記事一覧
第1回
第2回：環境構築編
第3回：環境構築編 トラブルシューティング
第4回：Google OAuth編
第5回：Google OAuth編 トラブルシューティング
第6回：アクセス制御編
第7回：アクセス制御編 トラブルシューティング
第8回：日本語対応編
第9回：日本語対応編 トラブルシューティング ※本記事
1. はじめに
このドキュメントは、『第8回：日本語対応編』を進める過程で実際に発生した問題と、その解決に至るまでのプロセスを記録したものです。
エラーは失敗ではなく、システムへの理解を深めるための最高のヒントです。各エラーから得られた学びを共有します。
ケーススタディ1：タイムゾーン設定がUIに表示されない
発生した事象
docker-compose.ymlにTZ: 'Asia/Tokyo'を設定した後、設定が反映されたかを確認しようとSettings（設定）画面を探したが、「General」（一般）や「Timezone」（タイムゾーン）といった項目がどこにも見当たらなかった。
原因の分析
これはOutlineのUIがアップデートされた結果のようです。TZという環境変数がコンテナに正しく設定されている場合、Outlineはそれを自動的に検知し、ワークスペース全体の標準時刻として強制的に適用します。
UI上でユーザーに選択させるまでもない「自明の設定」として扱われるため、UI上の設定項目自体が削除されたものと推測されます。
学び
UI上に設定項目が見当たらない場合、必ずしも「設定が失敗している」わけではありません。docker-compose.ymlの環境変数（TZなど）によって、UIよりも優先度の高いレベルで、自動的に設定が適用されている可能性があります。
最終的な動作（例：ドキュメントの最終更新日時がJSTで表示されるか）で確認するのが確実です。
ケーススタディ2：DEFAULT_LANGUAGEを設定しても、UIが英語のままだった
発生した事象
docker-compose.ymlにDEFAULT_LANGUAGE: 'ja_JP'を設定しコンテナを再起動したが、管理者アカウントでログインすると、UIが英語のままだった。
原因の分析
Outlineは、言語設定を2つの階層で管理しています。
- システム全体のデフォルト:
DEFAULT_LANGUAGE環境変数。 - ユーザー個人の設定:
Settings > PreferencesのLanguage設定。
DEFAULT_LANGUAGE設定が適用されるのは、「これから新しく参加するユーザー」の初期設定に対してのみです。
この設定を追加する前に管理者アカウントでログインしていたため、その時点で管理者個人の言語設定がEnglishとしてデータベースに保存されていました。
すでに保存されている「個人設定」が、「システム全体のデフォルト設定」よりも優先されるため、UIは英語のままでした。
解決策
- 既存ユーザー（管理者）:
Settings > Preferencesから、手動で言語をJapanese (日本語)に変更した。 - 新規ユーザー: 新しく招待した別のアカウントでログインしたところ、最初からUIが日本語で表示されることを確認し、
DEFAULT_LANGUAGE設定が正常に機能していることを証明した。
学び
設定変更が反映されない場合、「設定の適用範囲」（システム全体か、個人か）と「設定の優先順位」（どちらが優先されるか）を意識することが重要です。
ケーススタディ3：ロゴのアップロードで「Error 500」が発生
発生した事象
Settings > Detailsで、ワークスペースのロゴをPCからアップロードしようとしたところ、A network error occurredというメッセージが表示され、最終的にError 500（サーバー内部エラー）で失敗した。
原因の分析
これは、アクセス制御編の「招待メールが送信できない（SMTPサーバー未設定）」問題と、全く同じ根本原因です。
Outline（および多くの現代的Webアプリ）は、データ（テキスト、設定）とファイル（画像、添付ファイル）の保存場所を厳格に分けています。
- データ（テキストなど）: データベース（PostgreSQL）に保存されます。
- ファイル（ロゴ、画像など）: 専用のファイルストレージ（Amazon S3, Google Cloud Storage, MinIOなど）に保存されます。
docker-compose.ymlに、このファイルストレージの接続情報（S3_BUCKET, AWS_ACCESS_KEY_IDなど）を設定していなかったため、Outlineは「ロゴ画像を受け取ったが、保存場所が分からない」という内部パニックを起こし、Error 500を返しました。
解決策
これはlocalhostのバグではなく、本番運用を見据えた「仕様」です。
解決策は、docker-compose.ymlにファイルストレージ用の環境変数を追加し、Outlineがファイルを保存できる場所を指定することです。（※今回のプロジェクトでは、この設定は行わず、「ファイルストレージが必須である」という知見を得ることをゴールとしました）
学び
Error 500は、漠然とした「サーバーエラー」の総称ですが、ファイルアップロード時に発生した場合、基本的には「ストレージ設定の不備」を疑うのがいいでしょう。
現時点でOutlineを本番環境で運用するためには、SMTP（メール）とS3（ストレージ）の2つの外部サービス設定が必要になると思われます。
前の記事：第8回：日本語対応編
次の記事：準備中
【OSSでWiki構築】連載記事一覧
第1回
第2回：環境構築編
第3回：環境構築編 トラブルシューティング
第4回：Google OAuth編
第5回：Google OAuth編 トラブルシューティング
第6回：アクセス制御編
第7回：アクセス制御編 トラブルシューティング
第8回：日本語対応編
第9回：日本語対応編 トラブルシューティング ※本記事