# メッセージ・ガイドライン

この付録の情報を参照して、簡単に国際化できるメッセージを作成してください。

IPG.msgs.mkr.2
IPG.msgs.mkr.3
IPG.msgs.mkr.4
IPG.msgs.mkr.5
IPG.msgs.mkr.6
IPG.msgs.mkr.7
IPG.msgs.mkr.8

## ファイル命名
規約

この節では、ユーザ・メッセージのファイルに名前を付ける際の規約
について説明します。通常、メッセージ・ソース・ファイルには接尾辞`.msg`が付き、生成されるメッセージ・カタログには接尾辞`.cat`が付きます。その他にもメッセージ関連のファイルが存在する場合があります。ファイルがこれらの接尾辞をもつためには、次の条件を満たしている必要があります。

- X/Open準拠である。

- `gencat`コマンドを使用して`*.cat`ファイルになる。

## 原因と回復
情報

何が起こったのか、また、その状況を修復するために何ができるかを、可能な限りユーザに正確に説明します。

`Bad arg`というメッセージはあまり役に立ちませんが、次のメッセージなら、コマンドを機能させるためには何をすればよいかを正確にユーザに伝えることができます。

    Do not specify more than 2 files on the command line

同様に、`Line too long`というメッセージはユーザに回復情報を伝えていませんが、次のメッセージなら、もっと明確な回復情報をユーザに提供することができます。

    Line cannot exceed 20 characters

提供されているエラー・メッセージにもっと詳しい回復情報が必要な場合は、オンライン情報やヘルプの適切な場所に追加してください。

元のメッセージと書き直したメッセージの例については、IPG.msgs.mkr.8を参照してください。

## 翻訳者のためのコメント行

メッセージ
ソース・ファイルには、翻訳の過程で翻訳者に役立つコメントをいれておきます。これらのコメントは生成されるメッセージ・カタログの一部分ではありません。コメントはC言語でのプログラムのドキュメント化の助けとなるコメントに似ています。ドル記号のあとに空白がひとつ続くと、翻訳ツールと`gencat`により、コメントとして解釈されます。次にメッセージ・ソース・ファイルのコメント行の例を示します。

    $ This is a comment

コメント行を使用して、翻訳者や作成者に%s、%c、%dなどの変数が何を表すかを伝えます。たとえば、その変数が、ユーザ、ファイル、ディレクトリ、フラグなどを参照するかどうかを注意書きします。

コメント行はメッセージ・カタログの最後ではなく、コメントが参照するメッセージのすぐ下に置いてください。セット全体に関する包括的なコメントは、ソース・ファイル内の$set指示子のすぐ下に置きます。

メッセージ・カタログ内の使用しなくなったメッセージはコメント行に指定してください。

## プログラミング書式

メッセージのプログラミング書式については、次のリストを参照してください。

- メッセージを文節単位で構成しないでください。適切な時に完全なメッセージが出されるように、プログラム内でフラグその他の手段を使用して情報を渡してください。

- 既存のメッセージの%s文字列の変数として、ハードコードされた英語のテキストを使用しないでください。これはメッセージの構文でもあり翻訳できません。

- 文の最初の語は大文字にして、文や句の最後にはピリオドを使用してください。

- メッセージの最後の行を\n（バックスラッシュと小文字のn。改行を表わします）で終わらせてください。これは、メッセージが1行の場合にもあてはまります。

- メッセージの2行目以降の行は`\t`（バックスラッシュと小文字のt。タブを表わします）で始めてください。

- その他の行はすべて`\n\`（バックスラッシュ、小文字のn、バックスラッシュ。改行を表わします）で終わらせてください。

- 何らかの理由でメッセージが改行で終わらない場合は、作成者にコメントでその旨を知らせておきます。

- 各メッセージの前に、そのメッセージを呼び出したコマンド名とコロンを付けます。エラー・メッセージの場合はコマンド名の前にコンポーネント番号を付けます。コマンド名がメッセージ内にある場合は、次の例のように表示されます。

      >OPIE “foo: Opening the file.”

## 記述スタイル

次の記述スタイルについてのガイドラインには、用語、句読法、叙法、態、時制、大文字使用、その他の語法に関する項目が含まれています。

- 文形式を使用します。1行1文のメッセージが望ましいです。

- あいまいさをなくす必要がある場合は、冠詞（a、an、the）を付けます。

- 文の最初の文字は大文字にし、文の最後にはピリオドを使用します。

- 現在形を使用します。メッセージに未来形を使用しないでください。たとえば、次のような文を使用し、

  `The foo command displays a calendar.`

  次のような文は使用しないでください。

  `The foo command will display a calendar.`

- メッセージに一人称（Iまたはwe）を使用しないでください。

- 二人称の使用を避けてください。

  ヘルプおよび対話型テキスト以外では、youという語は使用しないでください。

- 能動態を使用します。次の例の1行目は元のメッセージ、2行目はより望ましい表現です。

  `MYNUM “Month and year must be entered as numbers.”MYNUM “foo: 7777-222 Enter month and year as numbers.\n”`

  7777-222はメッセージIDです。

- 命令法（コマンド句）と能動態の動詞を使用します。たとえば、specify、use、check、choose、wait などです。

- メッセージは肯定的な表現にします。次の例の1行目は元のメッセージ、2行目はより望ましい表現です。

  `BADL “Don't use the f option more than once.”BADL “foo: 7777-009 Use the -f flag only once.\n”`

- 名詞を動詞として使用しないでください。辞書に示されている文法の範疇内で語を使用します。ある語が辞書に名詞としてしか示されていない場合に、それを動詞として使用しないでください。たとえば、solution a problem（または、architect a system）のようには使用しないでください。

- 接頭辞や接尾辞を使用しないでください。翻訳者が、re-、un-、in-、non-で始まる語を理解できない可能性があり、接頭辞や接尾辞を使用しているメッセージは翻訳されると意図した意味をもたなくなるかもしれません。しかし、接頭辞が一般的に使用されている語の一部分に完全になっている場合は例外です。previousやprematureは使用できます。 nonexistent,は使用できません。

- 複数形は使用しないでください。error(s)のように括弧を使って単数形と複数形を示す表現はしないでください。これは翻訳することができません。単数形と複数形を示す必要がある場合は、error or errorsと記述してください。単数形か複数形かどちらが要求されてるのかによって2つの異なったメッセージが出されるようにコードを作成するのがよりよい方法です。

- 短縮形を使用しないでください。何かシステムにできないことを示すには、cannotという語を使用してください。

- 引用符を使用しないでください。単一引用符も二重引用符も同様です。たとえば、%s、%c、%dなどの変数や、コマンドに引用符を使用しないでください。ユーザが引用符を文字通りに入力するものと受け取る可能性があります。

- 行の終わりで語をハイフンで結ばないでください。

- 標準的な強調表示の方法を使用しないでください。また、その他の強調表示の方法の代わりに単語の先頭あるいはすべての文字を大文字にしたりしないでください。

- and/orを使用しないでください。この構文は他言語では存在しません。通常、必ずしも両方を必要とはしない場合は、orを使用するのが適当です。

- 24時間制を使用してください。a.m.やp.m.を使って時間を指定しないでください。たとえば、1:00 p.m.は13:00と記述します。

- 頭文字による略記は避けてください。頭文字による略記は、略記の方が略さずに書いたものよりよく知られている場合のみ使用してください。略記を複数形にする場合は、小文字のsをアポストロフィなしで付けます。使用する前にそれが商標でないことを確認してください。

- 一般向けではない用語は避けてください。たとえば、abort、argument、executeなどです。プロジェクト用語集を参照してください。

- 意味のある用語を維持してください。メッセージが意味をなし、翻訳可能であるようにする一方、元のメッセージ・テキストをできる限り保ってください。

## 使用方法の説明文

使用方法の説明文は、コマンド行に有効でないフラグが少なくともひとつ含まれている場合に、コマンドによって生成されます。フラグに関連付けられたデータがない場合や正しくない場合には、使用方法の説明文は使用してはなりません。そのような場合には、その問題に固有のエラー・メッセージが使用されます。

- 使用方法の説明文にはコマンド・シンタクスを示します。たとえば、`del`コマンドの使用方法の説明文は次のようなものです。

  `Usage: del {File ...|-}`

- コマンドの目的を定義する節は削除してください。

- 使用方法の説明文で使用する場合のみ、File、Directory、String、Numberなどの語（パラメータ）の最初の文字を大文字にします。

- コマンド行でパラメータを省略形にしないでください。経験のあるユーザにとってはNumがNumberを意味することは明らかですが、正しく翻訳されるように省略せずに記述してください。

- 使用方法の説明文では、区切り文字は次のものだけを使用してください。

  区切り文字 | 説明
  [] | パラメータはオプションです。
  { } | パラメータの選択肢が複数ありますが、そのうちのひとつが必要です。（下記のテキストを参照）
  | | パラメータをひとつだけ選択してください。[a|b]は、aかbのどちらかを選択するか、aもbもどちらも選択しなくてよいことを意味します。{a|b}は、aまたはbのどちらかを選択しなければならないことを意味します。
  .. | コマンド行でパラメータを繰り返すことができます。（この記号の前に空白がひとつ入ることに注意）
  - | 標準入力

- 使用方法の説明文のパラメータは角括弧や中括弧を必要としません。もし必要で、それしか選択肢がない場合は、次のようになります。

  `banner String`

- 使用方法の説明文では、コマンド行内で分けなければならないフラグの間に空白を入れます。たとえば次のようにします。

  `unget [-n] [-rSID] [-s] {File|-}`

- 区切りの空白なしで複数のフラグを一緒に使用できる場合は、コマンド行内で空白でフラグを分けないでください。次に例を示します。

  `wc [-cwl] {File ...|-}`

- コマンド行でのフラグの順序に特に意味がない場合は、フラグをアルファベット順に並べます。大文字と小文字が混在する場合は、小文字を先に置きます。

  `get -aAijlmM`

- 使用方法の説明文には長くて次行にわたっているものがあります。使用方法の説明文の行をどこで終了させるかはよく考えて決定してください。次の例は、`get`コマンドについての古い型の使用方法の説明文です。

  `Usage: get [-e|-k] [-cCutoff] [-iList] [-rSID] [-wString] [xList] [-b] [-gmnpst] [-l[p]] File ... Retrieves a specified version of a Source Code Control System (SCCS) file.`

## 標準メッセージ

POSIX.2ドキュメントに定義されている標準エラーをもつコマンドがあります。あてはまる場合は、POSIX.2に設定されているガイドラインに従ってください。

- ユーザにキーボード上のキーを選択させるために、`Press the ------ key`と告げます。それが特殊キーの場合も同様です（`Press Ctrl-D`など）。

- システムに負荷がかかりすぎる場合を除いて、ユーザに`Try again` `later`と告げる必要はありません。それは、メッセージから明らかであるべきです。

- メッセージ・テキストを記述する場合、コマンド行のテキストを表わすにはparameter（パラメータ）という語を使用し、数字データを表わすにはvalue（値）という語を使用します。

- command option（コマンド・オプション）という語ではなくflag（フラグ）という語を使用します。

- カンマを使用して値を1000分の1単位で区切らないでください。

- 1,000ではなく、1000とします。

- メッセージをアスタリスクで強調する場合、メッセージの最初に2つのアスタリスクを、メッセージの最後に2つのアスタリスクを使用してください。

  `** Total **`

- log in（ログインする）とlog off（ログオフする）は動詞として使用してください。

  `Log in to the system; enter the data; then log off.`

- user name（ユーザ名）、group name（グループ名）、login（ログイン）は名詞として使用してください。

  `The user name is sam. The group name is staff. The login directory is /u/sam.`

- ユーザ番号とグループ番号は、ユーザ名とグループに関連付けられた番号を参照します。

- superuser（スーパーユーザ）という用語を使用しないでください。 root user（root ユーザ）がすべての特権を持っているとは限りません。

- パラメータをもつコマンドを示すにはcommand string（コマンド文字列）という語を使用してください。

- 多くの同じメッセージが頻繁に出てきます。
  表A-1に、古いメッセージに代わる新しい標準メッセージをリストします。

## 新しい標準メッセージ

`使用すべき標準メッセージ` | `使用すべきでないメッセージ`
`Cannot find or open the file`. | `Can't open filename`.
`Cannot find or access the file`. | Can't access
`The syntax of a parameter is not valid`. | syntax error

## 正規表現の標準メッセージ

表A-2に、正規表現の標準エラー・メッセージを、各正規表現のエラーに関連付けられたメッセージ番号と共にリストします。

## 正規表現の標準メッセージ

`番号` | `使用すべき標準メッセージ` | `使用すべきでないメッセージ`
11 | Specify a range end point that is less than 256. | Range end point too large.
16 | The character or characters between \{ and \} must be numeric. | Bad number.
25 | `Specify a \digit between 1 and 9 that is not greater than the number of subpatterns.` | `\digit out of range`.
36 | A delimiter is not correct or is missing. | Illegal or missing delimiter.
41 | `There is no remembered search string`. | No remembered search string.
42 | There is a missing \( or \). | \(\) imbalance.
43 | Do not use \( more than 9 times. | `Too many \(`.
44 | Do not specify more than 2 numbers between \{ and \}. | More than two numbers given in \{ and \}.
45 | An opening \{ must have a closing \}. | } expected after \.
46 | The first number cannot exceed the second number between \{ and \}. | First number exceeds second in \{ and \}.
48 | Specify a valid end point to the range. | Invalid end point in range expression.
49 | For each [ there must be a ]. | `[ ] imbalance`.
50 | The regular expression is too large for internal memory storage. Simplify the regular expression. | `Regular expression overflow`.

## Sample Messages

以下に、元のメッセージと書き直したメッセージの例
を示します。元のメッセージそれぞれの下に書き直したメッセージがあります。

    AFLGKEYLTRS “Too Many -a Keyletters (Ad9)”

    AFLGKEYLTRS “foo: 7777-007 Use the -a flag less than 11 times.\n”
    FLGTWICE “Flag %c Twice (Ad4)”

    FLGTWICE “foo: 7777-004 Use the %c header flag once.\n”
    ESTAT “can't access %s.\n”

    ESTAT “foo: 7777-031 Cannot find or access %s.\n”
    EMODE “foo: invalid mode\n”

    EMODE “foo: 7777-033 A mode flag or value is not correct.\n”
    DNORG “-d has no argument (ad1)”

    DNORG “foo: 7777-001 Specify a parameter after the -d flag.\n”
    FLOORRNG “floor out of range (ad23)”

    FLOORRNG “foo: 7777-021 Specify a floor value greater than 0\n\

    \tand less than 10000.\n“
    AFLGARG “bad -a argument (ad8)”

    AFLGARG “foo: 7777-006 Specify a user name, group name, or\n\

    \tgroup number after the -a flag.\n“
    BADLISTFMT “bad list format (ad27)”

    BADLISTFMT “foo: 7777-025 Use numeric version and release\
    \tnumbers.\n”