better-writing

ライティング

このスキルでは、ラベル、エラー、空の状態、確認メッセージなどのインターフェース文言と、文言全体で使われる用語を作成・レビューします。製品で既に使われているトーンに合わせ、誤解を招いたり、次に進む方法を示さなかったりする文言を指摘します。

意図的なブランドボイスは欠陥ではありません。平易な表現からの逸脱を指摘するのは、不統一、曖昧さ、翻訳上のリスク、または状況にそぐわないトーンにつながる場合に限ります。単に好みに合うという理由での言い換えは、指摘事項ではありません。

text-transform、テキストの切り詰め、スマート句読点など、文言の表示方法は better-typography の対象です。エラーのマークアップ、アナウンス、アクセシブルな名前を設定する属性は better-accessibility の対象です。翻訳後の文字列を収めるための余白は better-layout の対象です。

まず既存の文字列を確認する

作成やレビューの前に、文言がどこにあるかを見つけ、変更箇所の周辺にある文言を読みます。

1. 翻訳呼び出し（t(、i18n.、<FormattedMessage、$t(）と、そこから読み込まれるロケールファイル（locales/**/*.json、messages/*.json、*.po、*.strings など）を検索します。文言は CMS や API から取得されることもあります。
2. 各オブジェクトに使われている名詞と、各アクションに使われている動詞を一覧にします。「project」や「workspace」、「Delete」や「Remove」などです。
3. 要素の種類ごとの大文字・小文字の使い方と、ボイスやコンテンツスタイルのガイドラインを確認します。

新しい文言では、その一覧にある用語を使います。同じものを異なる二つの名称で呼んでいる場合に限り、同義語を指摘事項とします。

一つのボイス、一つの用語体系

製品には一つのボイスがあり、既存の文言がそれを確立しています。局所的な編集で新たなボイスを作ることはできません。メニューで「Archive」としているなら、トーストで「Move to storage」とはしません。

複数のステップがあるフローでは、全体を通して一つの用語体系を使います。開始時は「Get started」、次へ進む操作には「Continue」または「Next」のどちらか、完了時は「Done」を使います。トーンは状況の重大さに応じて調整します。

状況	トーン
成功、オンボーディング、空の状態	温かみのある表現。軽やかでもかまいません
日常的な操作、設定	中立的で簡潔
エラー、取り消せない操作の確認	落ち着いた平易な表現。ふざけた調子は使いません
データ損失、セキュリティ	重大さを伝え、明確に

読者に直接語りかける

操作説明では「the user」ではなく「you」と書きます。エラーで「we」を使うと責任逃れに読めるため、「Unable to load content. Check your connection and try again.」のような表現を優先します。一人称を使う既存のボイスは、意味が明確であれば、影響の小さい文言ではそのまま使えます。

所有格は控えめに使います。「Your favorites」より「Favorites」が適切です。一つのフローで「My account」と「Your settings」のように視点を混在させてはいけません。

気の利いた表現より平易な言葉を

疲れている読者でも一度で理解できる言葉を選び、役に立たない語はすべて削除します。慣用句や口語表現、翻訳できないユーモアは使いません。

不要な性別表現は避けます。「each subscriber can post his or her recipes」ではなく、「Subscribers can post recipes」とします。入力デバイスに合わせて、「タップ」はタッチ操作に、「クリック」はポインター操作に使います。どちらの操作もあり得る場合は「選択」を使います。

文字列を一つのまとまりとして作る

変数の前後に断片をつなげて文を組み立ててはいけません（"You have " + n + " new messages" など）。言語によって語順が変わるためです。プレースホルダーを使って一つのメッセージを記述し、n === 1 ? "" : "s" のような処理ではなく、ロケールの複数形ルールを使います。複数形が二種類を超える言語は数多くあります。数値、日付、リストの書式設定には Intl を使います。パターンについては patterns.md を参照してください。

ボタンは動詞から始める

ボタンラベルは、アクションを表す動詞から始めます。「Send」、「Save draft」、「Delete project」のようにします。「OK!」や「Let's go!」は使いません。

アイコンのみのボタンでも、アクセシブルな名前には同じルールが適用されます。名前には「Trash icon」のようにアイコンそのものではなく、「Delete project」のようにアクションを指定します。この属性については better-accessibility を参照してください。

リンクにはリンク先を記述する

スクリーンリーダーのユーザーはページ上のリンク一覧から移動するため、リンクテキストは文脈がなくても意味が通じるようにします。「Click here」ではなく、「Read the billing docs」と書きます。

「Learn more」だけでは、ページに同じリンクが二つ表示されたときに意味が曖昧になります。それぞれに説明を付けて、「Learn more about exports」のようにします。

大文字・小文字の統一方針

要素の種類ごとにタイトルケースかセンテンスケースを選び、同じ種類のすべての箇所で統一します。プロジェクトに方針がない場合は、センテンスケースをデフォルトにします。「変更を保存」と「変更を破棄」が並んでいると、雑な印象になります。

設定にはオンの状態を記述する

トグルがオンのときに何が起きるかをラベルにします。「開封確認を送信する」なら、オフの状態をユーザーが推測できます。「開封確認を送信しない」では、トグルが二重否定になってしまいます。

設定へのパスを説明するのではなく、該当する設定に直接リンクします。「設定 > 通知 > メールに移動」ではなく、「通知設定」というリンクにします。

エラーには修正方法を、問題が起きた場所の近くに示す

エラーは指示であり、失敗したフィールドのそばに表示します。

悪い例	良い例
パスワードが短すぎます	8文字以上のパスワードを入力してください
日付が無効です	日付をDD/MM/YYYYの形式で入力してください
おっと！問題が発生しました。	保存できません。接続を確認して、もう一度お試しください。

責める表現、「おっと」、感嘆符は使いません。ヒントは「8文字未満を使わないでください」ではなく、「8文字以上を使用してください」のように肯定的に表現します。既知の要件はエラー時だけでなく、入力前にヘルパーテキストとして示します。同じエラーが繰り返し発生する場合は、発生しないように操作方法を再設計します。

確認よりも取り消しを優先する

アーカイブ、移動、ゴミ箱への削除など、操作を元に戻せて、頻繁に行われる場合は、取り消しを優先します。すぐに実行し、結果に取り消しの選択肢を提示します。「プロジェクトをアーカイブしました。元に戻す」

操作を元に戻せない場合、他の人に影響する場合、一度に多くの項目を破棄する場合は、実行前に確認します。確認画面では、結果が本文を読まなくても判断できるよう、操作の影響を繰り返し伝えます。

• タイトルには操作と対象を記載します。「『Q3レポート』を削除しますか？」とし、「よろしいですか？」とはしません。
• 本文には、失われるものと復元できないものを記載し、該当する場合は件数も示します。
• ボタンには動詞と対象を使います。Delete projectとCancelとし、YesやNoとはしません。
• アカウント、ワークスペース、リポジトリの場合は、対象の名前を入力するよう求めます。

テンプレートはpatterns.mdにあります。破壊的な操作のボタンには、他と区別できる色を使います（better-colors'）。

空の状態では次の操作を案内する

空の状態では、この場所の用途と内容の追加方法を説明し、次の操作を1つだけ明確に提示します。

<p>No results.</p>


<p class="font-medium">No projects yet</p>
<p class="text-sm text-zinc-500">Projects keep your tasks and files together.</p>
<button class="mt-4">Create a project</button>

フィルター適用後に結果がない場合は、検索内容を示して、解除方法を案内します。「『quarterly』の検索結果はありません。フィルターを解除」。永続的な情報を空の状態に置いてはいけません。内容が追加された時点で表示されなくなります。

読み込み中、保存中、成功時の文言についてはpatterns.mdを参照してください。

プレースホルダーには入力例を示す

プレースホルダーには、[email protected]やDD/MM/YYYYのように、そのフィールドが受け付ける形式の実用的な入力例を示します。指示は記載しません。フィールドに表示ラベルも必要かどうかについては、better-accessibilityを参照してください。

仕上げる前に

検出パターン	修正方法
Click here、hereというリンク、または同一のLearn moreリンクが2つ	リンク先を明示する
エラー文にOops、Something went wrong、または!が含まれている	失敗した内容と次の手順を伝える
" + n + "、文の断片を含むテンプレートリテラル、または=== 1 ? "" : "s"	複数形の引数を含む単一のICUメッセージにする
ダイアログのボタンに>OK<、>Yes<、または>No<	動詞と対象を使う
Are you sure	操作と対象を明示する
successfully	削除する：「変更を保存しました」
通常の指示に含まれるPlease	削除する
トグルのラベルがDon't、Disable、またはHideで始まる	オンの状態を記述する
aria-label="Trash"、"Close icon"、または"X"	操作を明示する：「プロジェクトを削除」「ダイアログを閉じる」
ロケールを指定していないtoLocaleDateString()、またはgetMonth()から生成した日付	ユーザーのロケールを指定したIntl.DateTimeFormatを使う
Save ChangesとDiscard changesが並んでいる	要素の種類ごとに大文字・小文字の使い方を統一する

報告

重大度。 HIGH はユーザーを誤導する、またはエラーからの復旧方法を隠蔽する問題です。復旧方法が示されていないエラーは常に HIGH であり、確認も取り消しもできない破壊的操作も同様です。MEDIUM はボイス、用語、または大文字表記の一貫性を損なう問題です。LOW は孤立した文言の推敲です。

検証。 すべてのラベルをそれが呼び出すアクションと照合し、すべてのエラーに明記された修正方法があるか確認し、すべての用語を用語一覧と照合してください。コンポーネントだけでなくロケールファイルも読んでください。サーバーまたは CMS から提供され、確認できなかった文字列は Not verified として報告してください。

形式。 検証結果は、違反している原則ごとにグループ化し、重大度順に並べ、根本原因ごとに 1 行で、それが出現するすべての箇所を列挙してください。

Severity	Location	Before	After	Why

Location は path/to/file:line です。Why には原則とユーザーへの影響を記載します。

HIGH が 1 件でも残っている場合は Block、それ以外の場合は Approve で締めくくり、残りは対応すべき作業として表に残してください。検査していない範囲を Approve にしてはいけません。報告すべき事項がない場合は、「No actionable writing findings」と述べ、検証結果を報告してください。