付録 A メッセージ・ガイドライン

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

「ファイル名の規約」




「原因および回復情報」




「翻訳者のためのコメント行」




「プログラム形式」




「記述形式」




「使用方法の説明文」




「標準メッセージ」




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




「メッセージの例」

ファイル名の規約

この節では、ファイルにユーザ・メッセージの名前を付ける際の規約を説明します。通常、メッセージ・ソース・ファイルには拡張子 .msg が付き、生成されるメッセージ・カタログには拡張子 .cat が付きます。その他にもメッセージ関連のファイルがある場合もあります。ファイルが.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

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

「メッセージの例」で、元のメッセージと書き直したメッセージの例を参照してください。

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

メッセージのソース・ファイルには、翻訳のプロセスで翻訳者に役立つコメントを入れることができます。そのようなコメントは、生成されるメッセージ・カタログの一部ではありません。このコメントは、C 言語でのプログラムのドキュメント化を助けるコメントに似ています。ドル記号 ($) のあとにスペース 1 つが続くと、翻訳ツールと 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 つの異なるメッセージのいずれかが発行されるようにコードを作成することです。

• 短縮形は使用しないでください。システムが処理できないことを表すには cannnot だけを使用してください。

• 引用符を使用しないでください。単一引用符も二重引用符も同じです。たとえば、%s、%c、%d などの変数やコマンドに引用符を付けないでください。ユーザは引用符を文字どおり入力するものだと思うかもしれません。

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

• メッセージでは一般的な強調表示の方法を取らないでください。また、単語の先頭あるいはすべての単語を大文字表記することによる強調表示の方法は用いないでください。

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

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

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

• 「禁句」は避けてください。たとえば、abort、argument、execute などです。プロジェクト用語集を参照してください。

• 意味のある用語を使うよう心がけてください。メッセージが確実に意味をなし、翻訳可能であるようにする一方、元のメッセージ・テキストの意味をできるだけ維持してください。

使用方法の説明文

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

• 使用方法の説明文にはコマンド形式を示します。たとえば、del コマンドの使用方法の説明文の例は次のとおりです。

     Usage: del {File ...|-}

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

• File、Directory、String、Number などの語 (パラメータ) の最初の文字は、使用方法の説明文で使用するときだけ大文字にします。

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

• 使用方法の説明文では、区切り文字は次のものだけを使用します。

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

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

     banner String

• 使用方法の説明文では、コマンド行中で分けられなければならないフラグの間にスペースを 1 つ入れます。次に例を示します。

     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.

• ユーザ番号とグループ番号は、ユーザの名前とグループに関連付けられた番号を指します。

• super user (スーパーユーザ) という用語は使用しないでください。root user (ルート・ユーザ) はすべての特権を持っているとは限りません。

• パラメータを持つコマンドを command string (コマンド文字列) と呼んでください。

• 多くの同じメッセージが何度も現われます。表 A-1 に、古いメッセージを置き換える新しい標準メッセージをリストします。

表 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 は、正規表現の標準エラーメッセージを、各正規表現エラーに関連付けられたメッセージ番号と共にリストします。

表 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.

メッセージの例

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

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"