言語ポリシー
次の 3 つの言語はそれぞれ独立して決めること。ある言語の選択から、ほかの言語を推測してはならない。
- 会話言語
- ソースコードの言語
- プロダクト / UI 言語
例えば次のような構成も成立する。
Conversation: Chinese
UI: Japanese
Code: English
これらの言語は混同せず、それぞれ自然な表現にすること。
コードの言語
意図的に他言語を含むリテラル値を除き、ソースコードはすべて標準的な英語で記述すること。
次の要素は英語で記述すること。
- 変数名
- 関数名
- メソッド名
- クラス名
- 型名
- インターフェース名
- 列挙型名
- モジュール名
- ファイル名
- ディレクトリ名
- コードコメント
- ドキュメント文字列
- 設定の識別子
- 内部のシンボル識別子
コードの識別子やコメントに英語以外の言語を使用しないこと。
特に次を使用してはならない。
- 日本語のかな文字
- 日本語による識別子
- 中国語による識別子
- ピンイン(pinyin)による識別子
- 日本語ローマ字(romaji)による識別子
禁止される識別子と、標準的な英語への置き換え例を示す。
kokyakuName -> customerName
shinseiStatus -> applicationStatus
kehuName -> customerName
yonghuId -> userId
ASCII に収めるためだけに、英語以外の単語をラテン文字へ音訳してはならない。求められるのは単なる ASCII ではなく、標準的な英語である。
リテラル値
他言語のテキストをリテラル値の一部として意図的に含めることは認められる。該当例は次のとおりである。
- UI の表示文言
- ローカライズリソース
- ユーザー向けのエラーメッセージ
- ローカライズされた内容を含むテストフィクスチャ
- ユーザーコンテンツの例
- 元の形式を保持しなければならないドメインデータ
リテラル値に他言語が含まれていても、英語以外の変数名やコメントを使ってよい理由にはならない。
会話言語
ユーザーが使用する言語で、自然にコミュニケーションすること。
会話では次の点を守ること。
- 自然に話す
- 親しみやすい口調にする
- 明確に伝える
- その言語の慣用に沿って表現する
- ユーザーのコミュニケーションスタイルに合わせる
不必要な言語の混用を避けること。
中国語で会話しているときも、実装内部で英語を使っているというだけの理由で、英語のフレーズを混ぜないこと。
次のものを指す場合は、英語を使ってよい。
- コードの識別子
- API 名
- ライブラリ名
- コマンド
- プロダクト名
- 確立された技術用語のうち、翻訳するとかえって分かりにくくなるもの
それ以外では、中国語で自然にコミュニケーションすること。
この原則はほかの言語でも同様である。
プロダクトと UI の言語
会話言語だけを根拠に、プロダクトの言語を推測してはならない。
プロジェクトの言語方針が文書化されていない場合は、本格的なユーザー向けコンテンツを実装する前に、次の点をユーザーへ確認すること。
- UI の主要言語
- 追加でサポートする言語
- 求められる文体やトーン
確認した言語ポリシーは AGENTS.md に記録し(必須のプロジェクトドキュメントを参照)、以後は同じ質問を繰り返さずその方針に従うこと。
再確認が必要なのは、次の場合だけである。
- ユーザーが要件を明示的に変更した場合
- 新しい要件が、文書化されたポリシーと競合する場合
- 求められる対象言語が本当に曖昧な場合
ユーザーが会話言語を変えても、それを理由に UI の言語を黙って変更しないこと。
言語横断の品質
会話・コード・プロダクトの言語が異なる場合は、言語間で文言を機械的に直訳しないこと。特に次の点を守る。
- 中国語の影響を受けた不自然な日本語や、中国語の文構造を持ち込んだ日本語を書かない。
- 自然な中国語の会話に、実装都合の英単語を理由なく混ぜない。
- 同じドメイン概念には、UI 全体で統一した訳語を使う。
- 中国語の開発会話から日本語の UI 用語を推測したり、英語のコード識別子から中国語の UI 用語を推測したりしない。
ユーザー向け UI 文言は、次の優先順位で評価すること。
- 対象言語における標準的な用法
- 正しい文法
- 明確な意味
- 適切な敬語レベル
- 理解しやすさ
- 使いやすさ
- プロダクト全体との一貫性
UI テキストは専門的で自然な表現にすること。直訳や機械翻訳のような不自然な言い回しを避ける。
重要な用語やトーンの選択に確信が持てない場合は、独自の慣例を勝手に作らず、ユーザーに尋ねること。