writing-error-messages

エラーメッセージの作成

クイックスタート

作成する前に、次の点を確認します。

1. 対象者： エンドユーザー、管理者、開発者、サポート担当者、運用担当者のいずれか。
2. 失敗したこと： どの操作が失敗し、何が正常に完了したか。
3. 原因： 判明しているか、不明か、ユーザーが修正できるか、サービス側か、サードパーティか、セキュリティ上の配慮が必要か。
4. 復旧方法： 読者が今できること、システムが次に行うこと、サポートを受けられる場所。

次の形式で作成します。

[What happened]
[Reassurance if useful]. [Why it happened, if known and safe]. [Specific next action]. [Backup path if it keeps happening].

例：

Unable to connect your account
Your changes were saved, but we couldn't connect the account because of an issue on our end. Try connecting again. If this keeps happening, contact support.

基本ルール

ルール	すること	避けること
何が起きたかを伝える	「ファイルを保存できませんでした。」	「問題が発生しました。」
影響を受けていないことを伝える	「下書きは保存されました。」	データが失われたのかとユーザーに不安を抱かせること
次の操作を示す	「カード番号を確認して、もう一度お試しください。」	「OK」／「閉じる」だけを選択肢にすること
平易な言葉を使う	「Dropbox に接続できませんでした。」	「Fetch に失敗しました」／「認証情報が拒否されました」
責任を押しつけない	「店舗名を入力してください。」	「店舗名を入力し忘れています。」
重要度に合わせる	落ち着いた、率直で、敬意のある表現	「おっと！」／冗談／くだけすぎた表現
安全な範囲で具体的にする	「過去の日付を入力してください。」	「入力が無効です。」
セキュリティ上必要な場合は一般的な表現にする	「メールアドレスまたはパスワードが無効です。」	「そのメールアドレスは登録されていますが、パスワードが間違っています。」

メッセージの構成要素

状況に必要な要素だけを使います。

要素	目的	形式
タイトル	失敗した操作を要約する	「変更を保存できませんでした」
本文	結果と原因を説明する	「変更内容はまだ開いたままですが、接続が切れたため保存できませんでした。」
主な操作	読者が行うことを伝える	「もう一度お試しください」、「詳細を更新」、「別のファイルを選択」
代替手段	別の方法を示す	「この問題が続く場合は、サポートにお問い合わせください。」
診断情報	技術担当者やサポートを支援する	エラーコード、リクエスト ID、期待値と受信値、ログの場所

可能であれば、UI の本文は1～2文にします。長い診断情報は、展開可能なテキスト、ログ、またはサポート用の情報に記載します。

参考資料

• 多数のメッセージを監査するとき、表現のトレードオフを判断するとき、または根拠となる情報源に基づく理由を確認するときは、references/source-backed-patterns.md を開きます。
• 複数のメッセージを書き換えるとき、またはこのスキルが適切な形式を出力しているか確認するときは、references/rewrite-examples.md を開きます。

入力検証とフォームエラー

フィールド単位のエラーの場合：

• メッセージはフィールドの横に表示し、長いフォームではエラーを先頭に要約します。
• 読者がメッセージとコントロールを結び付けられるよう、フィールドのラベルや質問と表現を合わせます。
• 間違っていることだけでなく、修正方法を伝えます。
• ユーザーが修正できるよう、入力内容を保持します。
• ユーザーが入力を終える十分な機会を得る前に検証しないでください。

適切な例：

Enter an email address
Enter a date in the past
Password must be at least 12 characters
Choose a file smaller than 10 MB

避ける例：

This field is required
Invalid input
You entered an illegal value
Validation failed

表示位置、アクセシビリティ、空の状態

• 読者が見ている場所、つまりフィールド、コントロール、トーストの表示元、または失敗した項目の近くにエラーを表示します。
• 色だけに頼らないでください。UI コードを扱う場合は、表示されるテキスト、アイコンまたはラベル、機械可読なセマンティクスを含めます。
• フォームページでは、製品のアクセシビリティパターンに従って、エラーの要約または最初のエラーにフォーカスを移します。
• 可能な限りユーザーの作業内容を保持します。
• 結果が空であることをエラーとして扱わないでください。失敗がなければ、「請求書が見つかりません」のような空の状態と、次に役立つ操作を表示します。

セキュリティとプライバシーの確認

具体的であれば常に良いとは限りません。詳細によってアカウントの存在、権限、個人情報、システム内部の情報、不正利用の兆候、セキュリティポリシーが明らかになるおそれがある場合は、一般的なメッセージを使います。

ログインとアカウント復旧では、一般的な表現を使います。

Invalid email or password
If an account exists for that email address, we'll send password reset instructions.

次の情報を明かさないでください。

That email exists, but the password is wrong
This account is locked
No account found for this email

ユーザーがサポートを必要とする場合は、安全な方法を案内します。サポート窓口、復旧手順、リクエスト ID、または監査に配慮した説明を提示してください。

開発者向けおよび CLI のエラー

読者が技術的な詳細をもとに対処できる場合は、次のように構造化して含めてください。

Could not read config file
Expected TOML at ./app.config.toml, but found invalid syntax on line 12: missing closing quote.
Fix the syntax and run `app deploy` again.

役立つ詳細：

• 失敗したコマンド、ファイル、フィールド、またはリソース。
• 期待されていた内容と、実際に受け取った内容。
• 最小限の修正方法、または次に実行する診断コマンド。
• サポートやデバッグに必要な場合は、リクエスト ID、エラーコード、またはログのパス。

対象読者が活用できる場合を除き、スタックトレース、生の例外名、内部サービス名は避けてください。

汎用的なエラーメッセージを求められた場合

製品でより良い対応ができないか確認せずに、「汎用的なエラーを書いて」との依頼をそのまま受け入れないでください。次の点を確認してください。

• ユーザーはどの操作を完了しようとしていましたか？
• コードまたはサービスで、何がこのエラーを引き起こしましたか？
• 原因は判明していますか、不明ですか、断続的に発生しますか、それともセキュリティ上の機密事項ですか？
• 何かが保存、送信、課金、削除されましたか、それとも変更されないままですか？
• ユーザーは自分で修正できますか、再試行できますか、時間を置けますか、別の方法を使えますか、それともサポートに問い合わせる必要がありますか？
• どのくらいの頻度で発生しますか？また、主要なフローを妨げますか？

原因が本当に不明な場合は、汎用的でありながら次の行動につながるメッセージを使用してください。

Something went wrong
Refresh the page and try again. If this keeps happening, contact support with request ID {request_id}.

最終確認

公開前に、メッセージが読者の次の疑問に答えていることを確認してください。

1. 何が起きましたか？
2. 何かを失ったり、重複して作成したりしましたか？
3. 安全に説明できる場合、なぜ起きましたか？
4. 次に何ができますか？
5. 何もしなかった場合、どうなりますか？
6. 修正方法で解決しない場合、どこでサポートを受けられますか？