（このページは現在翻訳中です。）
概要
文字列APIは、ユーザインターフェースで使用する言語のテキスト文字列を取得する方法です。国際化の問題を扱い、さまざまな設定や環境変数を使用して、すべてのユーザに最適なテキストを表示します。Moodleには、言語文字列を検索するために複数の場所を（順番に）検索するメカニズムがあります。これにより、言語文字列をプラグインとパッケージ化することができ、プラグインをインストールする際に言語ファイルを言語ディレクトリにコピーする手順を省略することができます。
Moodleは、マルチバイトセーフな文字列操作のためのsubstr、strlenなどの一般的な文字列関数も提供しています。UTF-8の文字列にはmbstringまたはiconvを使用し、typo3にフォールバックします。
基本的な概念
文字列を検索する必要がある場合、2つの基本的な情報が必要です。
- 文字列を提供するコンポーネント。
- 文字列の識別子。
例：関数呼び出しget_string('editingquiz', 'mod_quiz')は、現在の言語が英語である場合は "Editing quiz"、またはテキストの関連する翻訳を返します。ここで、文字列の識別子は "editingquiz" であり、文字列は "mod_quiz" コンポーネント（つまり、小テストの活動モジュール）によって提供されます。
プラグインへの言語ファイルの追加
プラグインの言語サポートは、プラグインディレクトリ内に lang/en/ のサブディレクトリを作成し、プラグインの英語の文字列ファイルをそこに配置することで追加されます。文字列ファイルの名前は、プラグインの コンポーネント名 に従うことが期待されており、plugintype_pluginname.php のような形式になります。
デフォルトの "en" 言語は、綴りや文法に関してはイギリス英語と同じであるオーストラリア英語です。アメリカ英語は別個の言語パック "en_us" として存在します。
デフォルトの英語以外の言語を含める必要はありません。ほとんどの承認されたプラグイン文字列は、言語パックの翻訳者によって自動的にAMOSにインポートされるため、翻訳作業が行われます。
言語ファイルに文字列を追加する
文字列は、文字列ファイルで提供される関連配列 $string を介して定義されます。配列のキーは文字列の識別子であり、値は指定された言語の文字列テキストです。
$string['editingquiz'] = 'Editing quiz';
$string['editingquiz_help'] = 'Help for editing quiz';
実行時パラメータ
文字列は、{$a} や {$a->foobar} のようなプレースホルダを定義することができます。これらのプレースホルダは、get_string() 関数呼び出しに渡される値で置き換えられます。
// 言語ファイルで定義された文字列。
$string['greeting'] = 'Dear {$a}';
$string['info'] = 'There are {$a->count} new messages from {$a->from}.';
// プレースホルダに対する値を渡す。
echo get_string('greeting', 'tool_example', 'Mr. Anderson');
echo get_string('info', 'tool_example', ['count' => 42, 'from' => 'Mr. Smith']);
ヘルプ文字列
ヘルプ文字列は、ヘルプのツールチップに表示されるテキストです。これらを定義するための特定の規則があります。
ヘルプ文字列の名前は、それらが適用される設定の文字列名で始まります。これにより、言語ファイル内で一緒に保持されます。
- stringname - ヘルプが提供される文字列の識別子であり、ヘルプポップアップのタイトルとして使用されることがあります。
- stringname_help - ヘルプテキストの文字列
- stringname_link - Moodle Docs内のパスを指定するオプションの文字列。必要な場合にのみ使用され、言語などを考慮したフッター内のリンクと同様に計算され、ヘルプテキストの後に "詳細なヘルプ..." というリンクとアイコンが表示されます。これらの文字列は翻訳する必要はないため、AMOS UIでは非表示にされます（一部のTinyMCE文字列を除く）。
- stringname_desc - configstringname の代わりに使用される管理者設定の説明
例:
$string['submissionsize'] = 'Submission size';
$string['submissionsize_help'] = 'Blah blah blah some useful text, optionally using Markdown syntax';
$string['submissionsize_link'] = 'mod/workshop/submission';
$string['submissionsize_desc'] = 'Default value for submission size. This value will be pre-filled and can be blah blah ...';
ヘルプ文字列のテキストは、短くてシンプルであるべきです。見出しやリンク、太字、表などは含まれません。最大で2つの短い段落で表現されます。
マークダウンは、"_help" 接尾辞を持つ文字列の基本的な書式設定に使用することができます。段落とリストに限定して使用することが推奨されています。マークダウンは、ヘルプ文字列にのみ使用することができ、他の言語文字列には使用できません。
詳細なヘルプリンク
ヘルプポップアップの下部にオプションの 詳細なヘルプ... リンクを表示するには、関連する "_help" 文字列の横に "_link" 接尾辞を持つ文字列が存在する必要があります。これらのリンク文字列は、'component/thing' のような短い相対パスで構成される必要があります（例：'mod/folder/view' や 'group/import'）。これは、ユーザの言語と適切なMoodleバージョンに基づいて、MoodleDocsへのリンクに変換されます。
例:
$string['groupimport_link'] = 'group/import';
とすると、'https://docs.moodle.org/32/en/group/import' のようなリンクが生成されます（Moodle 3.2の英語ユーザの場合）。このページは、実際の情報を提供するページへのリダイレクトページである必要があります。なお、'https://docs.moodle.org' の部分は $CFG->docroot から取得されます。
第2のオプションは、必要ならば絶対リンクを指定することができ、そのまま使用されます。
$string['patronising_link'] = <nowiki>'http://lmgtfy.com/?q=Moodle+for+dummies';</nowiki>
この場合、文字列が http:// または https:// で始まるかどうかで検出されます。このオプションは、プラグインのドキュメントが例えばGithubのウィキでホストされている場合に便利です。
第3のオプションは、リンクを %%WWWROOT%% で始めることです。これは $CFG->wwwroot に置き換えられます。これは、ヘルプをプラグイン内に保持したいコントリビュートされたプラグインに便利です。
ロールに対する用語
以下の用語は、一般的な意味で特定の役割を持つ人々を参照する必要がある場合に、英語（en）のヘルプ文字列で使用する必要があります。
- 参加者 - すべてのロールを持つ人々
- 教師 - ある種のファシリテーション/編集のロールを持つ人々
- 学生 - 主に学ぶために存在する人々
- ユーザ - サイト全体の人々
(Martin Dougiamas 16:13, 20 April 2010 (UTC): 私はこれを選択したと再確認しましたが、この選択肢に完全に満足しているわけではありません。ファシリテータ/モデレータなどの言葉を使用して、伝達主義的な教育方法よりもさりげなく継続的に促進したいと思っており、多くのMoodleユーザも同意するでしょう。ただし、これらの用語はコミュニティや議論でより一般的に使用されていると考えられ、使いやすさのために一貫したシステムを構築する必要がある観点から、より気を散らさず、ドキュメントにはより適しています。)
ファイル
文字列関数は以下で定義されています。
- lib/moodlelib.php - ロケール関連の関数
- lib/textlib.class.php - 一般的な文字列関数（substr、strlenなど）
関数と例
Moodleで使用される、ユーザの言語設定に基づいてローカライズされた文字列を取得/表示するための3つの主要な関数があります。
get_string()
現在のユーザに対してローカライズされた文字列を返します。
サイトでサポートされている任意の言語で文字列 "これは私のプラグインです" と表示するためには、言語ファイル（適切な lang ディレクトリにある）で次の識別子を使用する必要があります。
$string['plugintitle'] = 'これは私のプラグインです';
任意のサポートされている言語でこの文字列を表示したい場合は、次の関数を使用します。
echo get_string('plugintitle', 'module_pluginlangfilename');
もし言語文字列内で値を代入したい場合は、値の代入には {$a} を使用してください。$a は、翻訳文字列内で使用できるオブジェクト、文字列、または数値です。変数は $a である必要があり、シングルクォートで囲まれている必要があります。例えば、ドラッグアンドドロッププラグインで回答番号を表示したい場合は、以下を qtype_dragdrop.php（ドラッグアンドドロップ言語ファイル）に追加します。
$string['answerno1'] = '回答 {$a}'; //文字列/整数の代入
$string['answerno2'] = '回答 {$a->name}'; //オブジェクトメンバーの代入
そして、以下のように呼び出します。
// 整数を代入して文字列を取得する
get_string('answerno1', 'qtype_dragdrop', $number);
// オブジェクトメンバーの整数を代入して文字列を取得する
$user->number = 10;
get_string('answerno2', 'qtype_dragdrop', $user);
Moodle 2.3では、この関数に新しい引数 $lazyload が追加されています。lazyload を true に設定すると、get_string は文字列自体ではなく、lang_string オブジェクトを返します。
$stringobject = get_string('answerno', 'qtype_dragdrop', $number, true);
そして、文字列の取得は、文字列オブジェクトが最初に使用されるまで後回しにされます。オブジェクトは、その out メソッドを呼び出すか、オブジェクトを文字列にキャストすることによって使用することができます。例えば、直接的には以下のようにします。
(string)$stringobject
または、間接的には他の文字列内で使用するか、echo を使って表示します。例えば、以下のようにします。
echo $stringobject;
return "
{$stringobject}
";
注意: $lazyload を使用して、文字列を配列のキーとして使用しようとすると、オブジェクトは配列のキーとして使用できないため、致命的なエラーが発生します。
get_strings()
文字列名の配列を、特定のプラグイン用にローカライズされた文字列に変換します。この関数では、遅延読み込みはサポートされていません。
$txt = get_strings(array('enable', 'disable', 'up', 'down', 'none'), 'qtype_dragdrop');
echo $txt->up; //上向きのローカライズされた文字列を表示します
echo $txt->down //下向きのローカライズされた文字列を表示します
print_string()
get_string() 関数を使用して翻訳された文字列を出力します。
lang_stringクラス
Moodle 2.3では、特別なクラス（lang_string）が使用され、文字列リクエストのオブジェクト表現が作成されます。この場合、文字列の処理はオブジェクトが初めて使用されるまで行われません。このクラスは、文字列が生成される必要があるが必ずしも使用されない場所においてパフォーマンスを向上させるために特別に作成されました。例えば、管理者ナビゲーションツリーは1500以上の文字列を使用しますが、通常はそのうちの1/3しか実際に印刷されません。パフォーマンスの利点は、使用されていない文字列を実際に処理せず、ページに必要な処理を減らすことで実現されます。
lang_stringクラスは2つの方法で使用することができます。
- get_string 関数の第4引数である $lazyload を true に設定する。
$string = get_string('yes', 'qtype_dragdrop', null, true);
- 直接インスタンス化する。
$string = new lang_string('yes', 'qtype_dragdrop', null, 'en');
文字列マネージャ
上記にリストされたほとんどの関数は、文字列マネージャクラスが提供するメソッドのラッパーです。一部の文字列関連の機能は、マネージャのメソッドを直接呼び出すことでのみ利用できます。
$stringman = get_string_manager();
ファクトリー関数get_string_manager()は、サイトのインストール初期段階ではcore_string_manager_installのシングルトンインスタンスを返し、通常のすべての状況ではcore_string_manager_standardのインスタンスを返します。これらのマネージャはcore_string_managerインターフェースを実装しています。インターフェースで提供されるメソッドは以下の通りです。
- get_string()
- 指定されたコンポーネントの文字列を指定された言語でローカライズして返します。現在のユーザの言語とは異なる言語での文字列の翻訳を取得するために使用できます。
- string_exists()
- 指定された文字列は実際に存在しますか？通常、以下のようなコードで確認されます。
if (get_string_manager()->string_exists('stringidentifier', 'component_name')) {
// 何か処理を行う
}
- string_deprecated()
- 文字列は非推奨ですか？詳細については文字列の非推奨化を参照してください。
- get_list_of_countries()
- 国の名前のローカライズされたリストを国のキーでソートして返します。
- get_list_of_languages()
- コードキーでソートされたローカライズされた言語のリストを返します。
- translation_exists()
- 指定された言語の翻訳が存在するかどうかをチェックします。
- get_list_of_translations()
- インストールされている言語パックのローカライズされたリストを返します。
- get_list_of_currencies()
- 既知の通貨のローカライズされたリストを返します。
- load_component_strings()
- 特定のコンポーネントのすべての文字列をロードします。
- reset_caches()
- すべてのキャッシュを無効にし、マネージャが使用している場合に使用されます。
- get_revision()
- 文字列のリビジョンカウンターを返します。
カスタム文字列マネージャ
Moodle 2.9 プラグインは、文字列マネージャのカスタム実装を提供することができます。これは実験的および/または開発シナリオでのみ使用されることを想定しており、通常の本番環境では使用されません。使用事例と実装の詳細については、MDL-49361を参照してください。このような実装の例は、moodle-local_stringman.gitリポジトリで見つけることができます。
// カスタム文字列マネージャクラスは、メインのconfig.phpファイルで定義することができます。
$CFG->customstringmanager = '\local_stringman\dummy_string_manager';
textlib（core_text）クラス
textlibクラスは、UTF-8テキスト上で安全な関数を提供します。textlibクラスは、文字列操作に使用する一連の静的関数を提供し、setup.phpに含まれます。
Moodle 2.6 Moodle 2.6では、textlibクラスは core_text という名前に変更されました。
asort()
ロケールに対応したソートで、キーの関連性は保持され、値はアルファベット順にソートされます。
code2utf8
Unicode 値に対応する UTF-8 文字列を返します。
convert
異なるエンコーディング間でテキストを変換します。iconv 拡張機能を使用し、//TRANSLIT パラメータを使用します。typo3 にフォールバックします。
encode_mimeheader
MIME メールメッセージで使用される正しい Base64 エンコードされたヘッダを生成します。
entities_to_utf8
すべての数値エンティティ &#nnnn; または &#xnnn; をUTF-8に変換します。
specialtoascii
上位の Unicode 文字をプレーンな ASCII に変換し、返される文字列には変換されていない Unicode 文字が含まれる可能性があります。
strlen
マルチバイトに対応した安全な strlen() 関数です。UTF-8 の場合は iconv を使用し、typo3 にフォールバックします。
strpos
文字列内でサブ文字列の最初の出現位置を検索します。UTF-8 専用の安全な strpos() 関数であり、iconv を使用します。
strrpos
文字列内で部分文字列の最後の出現位置を検索します。UTF-8 専用の安全な strrpos() 関数であり、iconv を使用します。
strtolower
マルチバイトに対応した安全な strtolower() 関数です。mbstring を使用し、typo3 にフォールバックします。
strtotitle
各単語の最初の文字を大文字にします - 単語はスペースで区切られている必要があります。
strtoupper
マルチバイトに対応した安全な strtoupper() 関数です。mbstring を使用し、typo3 にフォールバックします。
substr
マルチバイトに対応した安全な substr() 関数です。UTF-8 の場合は iconv を使用し、typo3 にフォールバックします。
trim_utf8_bom
Unicode 文字列から BOM を削除します。詳細についてはこちら
utf8_to_entities
Unicode文字列内のすべての127より大きい文字を数値エンティティ &#nnnn; または &#xnnn; に変換します。
FAQ
lang_stringオブジェクトはいつ使用すべきですか？
lang_stringオブジェクトは、文字列が必要ではないが生成される必要がある場合に使用するように設計されています。管理者ナビゲーションツリーは、lang_string オブジェクトが使用されるべき良い例です。もっと実用的な例としては、文字列が印刷されない可能性のある任意のクラスがあります（クラスはすべてレンダラによってレンダリングされるため、何が行われるかはわかりません。
lang_stringオブジェクトを使用しない場合はいつですか？
lang_string オブジェクトをすぐに使用する場合は使用しないでください。すぐに処理されるため利点はなく、実際にはクラスが lang_string オブジェクトのインスタンス化が必要になるため、むしろ負荷がかかる可能性がありますが、get_string はそれを必要としません。
lang_stringの制限
lang_string オブジェクトは、配列のオフセットとして使用することはできません。それを行うと、PHPがエラーをスローします（オブジェクトのプロパティとして使用することはできます！）
2つのオブジェクトの文字列プロパティを比較する方法
collatorlib_property_comparison クラスを使用して、2つのオブジェクトのプロパティを比較することができます。
コロン記号はハードコードするべきか、言語の文字列に含めるべきか？
コロン記号はハードコードするべきではありません。なぜなら、言語によっては異なる記号を使用したり、コロン記号の前後にスペースがある場合があるためです。代わりに、言語の文字列にコロン記号を含めることができますが、本当に必要かどうかよく考えてください。フィールドラベルにコロン記号を含めることはおすすめしません（既存のハードコードされたコロン記号を削除するためのMDL-12192があります）。
// 句読点をハードコードしないでください:
$string['fieldname'] = 'Name';
echo get_string('fieldname', 'mod_foobar') . ': ' . $somevalue;
// ハードコードされたコロンがない場合、少し改善されます:
$string['fieldname'] = 'Name: ';
echo get_string('fieldname', 'mod_foobar') . $somevalue;
// 単語の順序を仮定しない場合、より良いです:
$string['fieldname'] = 'Name: {$a->name}';
echo get_string('fieldname', 'mod_foobar', ['name' => $somevalue]);
既存の言語文字列を変更するか新しい言語文字列を作成するか？
1.x時代には翻訳用のブランチがなかったため、新しい文字列が必要でした。2.0以降では、マスターでの変更において、文字列の構造や意味の変更（{$a}プレースホルダーの追加や削除など）は受け入れられます。このような文字列は AMOS で古いものとして強調表示されます。もちろん、言語パックのメンテナーがそれに注意を払わない場合は、不一致が発生する可能性がありますが、これは言語パックのバグと見なされます。
新しい文字列が導入されると、未使用の文字列が蓄積されないように、古い文字列は 非推奨化または削除されるべきです。
- A) 基本的に、（マスターのみの問題について考えると）次のように考えています:
-
- どんな変更も許されます (意味的または構造的)。新しいMoodleのバージョンがリリースされたときに、古い文字列は使用されないので、残す意味がありません。したがって、私たちは古い文字列を100%忘れることができます。もちろん、文字列が根本的に異なる場合、新しい完全に異なる文字列を作成することは意味があるかもしれません (そして、次のポイントに進みます)。
- 何らかの理由で文字列の使用を中止する場合（機能がなくなったとか、既存の文字列を変更するのではなく、新たに別の文字列を作成することにしたとか）:
- もし古い文字列が本当に特殊なものであれば（再利用に適さない）、安全に削除を進めることができます。
- もしその文字列がプラグインに属するものであれば、IMOはその削除を進めることができます（プラグイン文字列の再利用は許可されるべきではありません）。
- しかし、その文字列が一般的で（再利用可能で）、プラグインの一部でない場合、その文字列は非推奨としなければなりません。
- B) また、安定版に関連する問題については、小さな意味的な変更のみ許可されます。構造の変更や非推奨化、削除は一切ありません。これからもありません。もし異なる表示が必要な場合は、常に新しい文字列を使用します。マスターに適用する場合、これらの変更は 標準的な古い文字列の非推奨化も意味します。古い文字列と新しい文字列の間でCPY命令は実行されません（最も安全で、簡単で、一貫した動作です。いくつかのケースでは命令が許容される場合もあるかもしれませんが、考えすぎはやめましょう。今すぐやめましょう！）。
ユーザ名のプレースホルダ
文字列の中には、ユーザ名を表示するためのプレースホルダが含まれている場合があります。よくある例としては、さまざまな電子メールのテンプレートやウェルカムメッセージがあります。このような場合、開発者は、テキストをカジュアルで親しみやすいものにするために、ユーザのファーストネームだけを使用したくなるかもしれません：
// これを行わないでください
$string['welcome'] = 'Hello {$a}! Welcome to the course.';
しかし、文化や機関によっては、ファーストネームではなく、フルネームやラストネームを使用することを望む場合もあります。このような文字列を簡単にカスタマイズし、lastnameとalternatenameのプレースホルダを利用できるようにするには、次のパターンを使用する必要があります。
与えられたコンポーネントの言語文字列ファイルに、名前のデフォルト表示を定義させます:
$string['welcome'] = 'Hello {$a->firstname}! Welcome to the course.';
次に、文字列を使用したファイルで:
$namefields = [
'fullname' => fullname($USER),
'alternativefullname' => fullname($USER, true),
];
foreach (\core_user\fields::get_name_fields() as $namefield) {
$namefields[$namefield] = $USER->{$namefield};
}
echo get_string('welcome', 'xyz_component', $namefields);
そうすれば、文字列をローカルにカスタマイズして、必要に応じて次のプレースホルダを自由に組み合わせて使うことができます: firstnamephonetic, lastnamephonetic, middlename, alternatename, firstname, lastname, fulname, alternatfullname
// 文字列をローカルにカスタマイズしたバリアント
$string['welcome'] = 'Welcome to the course, {$a->fullname}';
関連項目
- 出力関数
- コアAPI
- AMOS
- コーディングスタイルのセクション '言語文字列'
- 文字列の非推奨化
- 英語の言語文字列の改善
