開発者エリア/言語ストリング: Difference between revisions
From Mahara Wiki
(99 intermediate revisions by the same user not shown) | |||
Line 1: | Line 1: | ||
国際化 (i18n) およびローカライゼーション (l10n) の目的のため、Maharaでユーザに表示されるストリングすべてはコードに直接記述されるのではなく、「言語ストリング」に保存された上で'''get_string($identifier, $section)'''関数により表示されます。この関数は外国語の'''言語パック'''がインストールされているか確認します。また、'''カスタム言語ファイル'''が存在するか確認して存在する場合、そのストリングを使用します。そうでない場合、コア言語ファイルに戻ります。 | |||
国際化 (i18n) およびローカライゼーション (l10n) の目的のため、Maharaでユーザに表示されるストリングすべてはコードに直接記述されるのではなく、「言語ストリング」に保存された上で '''get_string($identifier, $section)''' 関数により表示されます。この関数は外国語の'''言語パック'''がインストールされているか確認します。また、'''カスタム言語ファイル''' | |||
=== PHPでのget_string()の使用方法 === | === PHPでのget_string()の使用方法 === | ||
Line 10: | Line 8: | ||
* '''section''': 言語ストリングが存在するファイルです。これは技術的に任意です。無視された場合、多くの一般的なコアストリングを含むデフォルトの「mahara」セクションが割り当てられます。 | * '''section''': 言語ストリングが存在するファイルです。これは技術的に任意です。無視された場合、多くの一般的なコアストリングを含むデフォルトの「mahara」セクションが割り当てられます。 | ||
** 例: | ** 例: | ||
*** | *** admin: コアの「admin」セクション用です。 | ||
*** | *** artefact.blog: 「blog」アーティファクトプラグイン用です。 | ||
*** | *** theme.primaryschool: 「primaryschool」テーマ用です。 | ||
* '''params''': (任意) 言語ストリングには1つまたはそれ以上の[http://nz1.php.net/sprintf sprintf()]パラメータを含めます。言語ストリング内に存在する場合、get_string() がコールされて使用するストリングを配置するためにパラメータ値との合致が要求されます。パラメータは異なる語順の言語への翻訳時に役立ちます。 | * '''params''': (任意) 言語ストリングには1つまたはそれ以上の[http://nz1.php.net/sprintf sprintf()]パラメータを含めます。言語ストリング内に存在する場合、get_string()がコールされて使用するストリングを配置するためにパラメータ値との合致が要求されます。パラメータは異なる語順の言語への翻訳時に役立ちます。 | ||
'''例:''' | '''例:''' | ||
< | <syntaxhighlight lang="php"> | ||
$yesstr = get_string('yes'); // lang/en.utf8/mahara.php | $yesstr = get_string('yes'); // lang/en.utf8/mahara.php | ||
$clamstr = get_string('pathtoclam', 'admin'); // lang/en.utf8/admin.php | $clamstr = get_string('pathtoclam', 'admin'); // lang/en.utf8/admin.php | ||
Line 25: | Line 23: | ||
// 複数形ストリング。最初の変数は複数形アイテムの数です。get_stringは単一または複数のどちらを使うか決定するために変数を使用します (英語以外の言語では2つ以上の複数形が存在する場合があります)。 | // 複数形ストリング。最初の変数は複数形アイテムの数です。get_stringは単一または複数のどちらを使うか決定するために変数を使用します (英語以外の言語では2つ以上の複数形が存在する場合があります)。 | ||
$updatefilesstr = get_string('updatednfiles', 'mahara', 5); | $updatefilesstr = get_string('updatednfiles', 'mahara', 5); | ||
</ | </syntaxhighlight> | ||
=== Dwooテンプレートからの言語ストリング使用方法 === | === Dwooテンプレートからの言語ストリング使用方法 === | ||
Line 31: | Line 29: | ||
あなたは {} タグを使ってDwoテンプレート内部から言語ストリングにもアクセスできます: | あなたは {} タグを使ってDwoテンプレート内部から言語ストリングにもアクセスできます: | ||
< | <syntaxhighlight lang="smarty"> | ||
{str tag='identifier' section='section' arg1='first param value' arg2='second param value'} | {str tag='identifier' section='section' arg1='first param value' arg2='second param value'} | ||
</ | </syntaxhighlight> | ||
これを動作させるコードは次のとおりです: htdocs/lib/dwoo/mahara/plugins/function.str.php | これを動作させるコードは次のとおりです: htdocs/lib/dwoo/mahara/plugins/function.str.php | ||
Line 40: | Line 38: | ||
==== プリフェッチ ==== | ==== プリフェッチ ==== | ||
あなたはJavaScriptにも言語ストリングを使用できます。最初にsmarty()関数に$pagestrings変数を渡して言語ストリングを読み込んでください ... | |||
< | <syntaxhighlight lang="php"> | ||
// Providing a $pagestrings variable to smarty() | // Providing a $pagestrings variable to smarty() | ||
$pagestrings = array( | $pagestrings = array( | ||
Line 51: | Line 49: | ||
'mahara' => array('yes') | 'mahara' => array('yes') | ||
); | ); | ||
</ | </syntaxhighlight> | ||
... そして、次にJavaScriptのget_string()関数を使用して言語ストリングにアクセスできます。これは「section」セクションを除外する以外、PHPのget_string()に似ています (注意: これはあなたが2つの言語ストリングを同じIDで異なるセクションに含めないことを意味します)。また、「%s」タイプの置換パラメータのみ受け付けます。 | ... そして、次にJavaScriptのget_string()関数を使用して言語ストリングにアクセスできます。これは「section」セクションを除外する以外、PHPのget_string()に似ています (注意: これはあなたが2つの言語ストリングを同じIDで異なるセクションに含めないことを意味します)。また、「%s」タイプの置換パラメータのみ受け付けます。 | ||
< | <syntaxhighlight lang="html4strict"> | ||
<script type="text/javascript"> | <script type="text/javascript"> | ||
alert(get_string('yes')); | alert(get_string('yes')); | ||
confirm(get_string('discardpageedits', 'first param value')); | confirm(get_string('discardpageedits', 'first param value')); | ||
</script> | </script> | ||
</ | </syntaxhighlight> | ||
特定のJavaScriptファイルがDwooに含まれる場合にJavaScriptのget_string()で多くのJavaScriptストリングを常に使用できるようハードコードされています。このリストに関して「htdocs/lib/web.php」の関数「jsstrings」をご覧ください。 | 特定のJavaScriptファイルがDwooに含まれる場合にJavaScriptのget_string()で多くのJavaScriptストリングを常に使用できるようハードコードされています。このリストに関して「htdocs/lib/web.php」の関数「jsstrings」をご覧ください。 | ||
Line 66: | Line 64: | ||
==== AJAX経由で動的に取得する ==== | ==== AJAX経由で動的に取得する ==== | ||
Mahara 15. | Mahara 15.10現在、あなたはAjax経由で動的に言語ストリングを取得できます。'''get_string_ajax()'''関数を使用してください。事前に取得した言語ストリングとは異なり、動的に取得したストリングにはセクションパラメータおよび他のパラメータを含めます。この機能はget_string_ajax()リクエストごとの結果をキャッシュします。 | ||
この関数は非同期に動作するため、alert()およびconfirm()のコールには'''適していません'''。関数自体はユニークIDを含む<span>タグのプレースホルダを返します。プレースホルダはAJAXコールが戻った際に評価されたストリングと置換されます。そのため、あなたが直接alert()、confirm()またはその他の即時出力メソッドを使用する場合、ユーザには結果のストリングではなく、プレースホルダが表示されます。 | この関数は非同期に動作するため、alert()およびconfirm()のコールには'''適していません'''。関数自体はユニークIDを含む<span>タグのプレースホルダを返します。プレースホルダはAJAXコールが戻った際に評価されたストリングと置換されます。そのため、あなたが直接alert()、confirm()またはその他の即時出力メソッドを使用する場合、ユーザには結果のストリングではなく、プレースホルダが表示されます。 | ||
< | <syntaxhighlight lang="html4strict"> | ||
<script type="text/javascript"> | <script type="text/javascript"> | ||
// 正解! ページのHTMLに戻り値を挿入します | // 正解! ページのHTMLに戻り値を挿入します | ||
Line 79: | Line 77: | ||
alert(get_string_ajax('cannotremove', 'auth')); | alert(get_string_ajax('cannotremove', 'auth')); | ||
</script> | </script> | ||
</ | </syntaxhighlight> | ||
=== 言語ファイルの構造 === | === 言語ファイルの構造 === | ||
言語ファイルは'''{section}.php'''のように名前付けされます。ここでの「section」はセクション値としてget_string()に渡されます。これには「$string」と呼ばれる配列にキーを追加するための一連の行が含まれます。すべてのMaharaライブラリファイルのようにウェブブラウザからのアクセスを防ぐため、[[Developer_Area/Pagetop_Constants#INTERNAL|内部定数]]のチェックから始めてください。 | 言語ファイルは'''{section}.php'''のように名前付けされます。ここでの「section」はセクション値としてget_string()に渡されます。これには「$string」と呼ばれる配列にキーを追加するための一連の行が含まれます。すべてのMaharaライブラリファイルのようにウェブブラウザからのアクセスを防ぐため、[[Developer_Area/Pagetop_Constants#INTERNAL|内部定数]]のチェックから始めてください。 | ||
< | <syntaxhighlight lang="php"> | ||
<?php | <?php | ||
defined('INTERNAL') || die(); | defined('INTERNAL') || die(); | ||
Line 97: | Line 95: | ||
1 => 'あなたは %s ファイルを更新しました。', | 1 => 'あなたは %s ファイルを更新しました。', | ||
); | ); | ||
</ | </syntaxhighlight> | ||
=== 複数形ストリング === | === 複数形ストリング === | ||
正確には'''加算可能ストリング''' | 正確には'''加算可能ストリング'''と読んだ方が良いのかもしれません。英語には2つの複数形があります: 単数形 (1つ) および複数形 (2つ以上)。他の言語には複数の複数形があります。例えばスロベニア語の場合、あなたが1つ、2つまたは3つ以上を持つかにより単語の語尾が異なる2通りの複数形があります。 | ||
英語とは異なる複数形を持つ言語を翻訳できるようにしたい場合、「あなたには 3 つのブログがあります/あなたには 1 つのブログがあります」のように数字でカウントできる特別な構文のストリングがあります。 | 英語とは異なる複数形を持つ言語を翻訳できるようにしたい場合、「あなたには 3 つのブログがあります/あなたには 1 つのブログがあります」のように数字でカウントできる特別な構文のストリングがあります。 | ||
Line 106: | Line 104: | ||
まず、get_string()を使用する場合、第1カスタムパラメータとしてストリングのアイテムカウント数を渡してください: | まず、get_string()を使用する場合、第1カスタムパラメータとしてストリングのアイテムカウント数を渡してください: | ||
< | <syntaxhighlight lang="php"> | ||
get_string('fileattachedportfolioitems', 'artefact.file', $numitems); | get_string('fileattachedportfolioitems', 'artefact.file', $numitems); | ||
</ | </syntaxhighlight> | ||
次に言語ファイルでストリング配列を作成してください。英語の場合、キーが「0」の配列のアイテムは単数形のストリング、キーが「1」の配列のアイテムは複数形となります。 | 次に言語ファイルでストリング配列を作成してください。英語の場合、キーが「0」の配列のアイテムは単数形のストリング、キーが「1」の配列のアイテムは複数形となります。 | ||
< | <syntaxhighlight lang="php"> | ||
$string['fileattachedtoportfolioitems'] = array( | $string['fileattachedtoportfolioitems'] = array( | ||
0 => 'このファイルはあなたのポートフォリオの 1 の他のアイテムに添付されています。', | 0 => 'このファイルはあなたのポートフォリオの 1 の他のアイテムに添付されています。', | ||
1 => 'このファイルはあなたのポートフォリオの %s の他のアイテムに添付されています。', | 1 => 'このファイルはあなたのポートフォリオの %s の他のアイテムに添付されています。', | ||
); | ); | ||
</ | </syntaxhighlight> | ||
この構文により、英語とは異なる複数形を持つ他の言語を実装できます。それぞれの言語にはどのキーがカウント数を返すか決定するpluralfunction関数を含むlangconfig. | この構文により、英語とは異なる複数形を持つ他の言語を実装できます。それぞれの言語にはどのキーがカウント数を返すか決定するpluralfunction関数を含むlangconfig.phpファイルがあります。英語では単数形に「0」、複数形に「1」を返します。恐らく、他の言語はさらに多いまたは少ないキーを返すと思われます。そのため、別の言語パックの同じストリングは以下のようになります: | ||
< | <syntaxhighlight lang="php"> | ||
$string['fileattachedtoportfolioitems'] = array( | $string['fileattachedtoportfolioitems'] = array( | ||
0 => 'Ta datoteka je pripeta k %s drugemu elementu v vašem listovniku.', | 0 => 'Ta datoteka je pripeta k %s drugemu elementu v vašem listovniku.', | ||
Line 126: | Line 124: | ||
3 => 'Ta datoteka je pripeta k %s drugim elementom v vašem listovniku.', | 3 => 'Ta datoteka je pripeta k %s drugim elementom v vašem listovniku.', | ||
); | ); | ||
</ | </syntaxhighlight> | ||
詳細は[[Language Packs/Plural forms]] | 詳細は[[Language Packs/Plural forms]]および https://bugs.launchpad.net/mahara/+bug/901051 をご覧ください。 | ||
カウンタパラメータは最初のパラメータにしてください。あなたがカウンタパラメータをストリングの最初に表示したくない場合、[http://nz2.php.net/manual/en/function.sprintf.php#example-4957 sprintf位置指定子] | カウンタパラメータは最初のパラメータにしてください。あなたがカウンタパラメータをストリングの最初に表示したくない場合、[http://nz2.php.net/manual/en/function.sprintf.php#example-4957 sprintf位置指定子]で移動してください: | ||
< | <syntaxhighlight lang="php"> | ||
$string['setprobationpoints'] = array( | $string['setprobationpoints'] = array( | ||
0 => 'Set probation points to %2$d for %1$d user.', | 0 => 'Set probation points to %2$d for %1$d user.', | ||
1 => 'Set probation points to %2$d for %1$d users.'; | 1 => 'Set probation points to %2$d for %1$d users.'; | ||
); | ); | ||
</ | </syntaxhighlight> | ||
'''メモ:''' Maharaにはこのフォーマットに従わない古い複数形ストリングが相当数含まれます。あなたが古い複数形ストリングを見つけた時に直してくれると助かります。翻訳者に分かりやすくするため、正しいストリングには古いストリングとは異なるストリング名を使用してください。あなたが古いストリングのすべての参照を削除できた場合のみ、古いストリングを削除してください。 | '''メモ:''' Maharaにはこのフォーマットに従わない古い複数形ストリングが相当数含まれます。あなたが古い複数形ストリングを見つけた時に直してくれると助かります。翻訳者に分かりやすくするため、正しいストリングには古いストリングとは異なるストリング名を使用してください。あなたが古いストリングのすべての参照を削除できた場合のみ、古いストリングを削除してください。 | ||
Line 147: | Line 145: | ||
詳細なsprintf()フォーマット文法は[https://www.php.net/manual/en/function.sprintf.php#refsect1-function.sprintf-parameters ここで]確認できますが、あなたが知る必要のある内容は以下の少しだけです: | 詳細なsprintf()フォーマット文法は[https://www.php.net/manual/en/function.sprintf.php#refsect1-function.sprintf-parameters ここで]確認できますが、あなたが知る必要のある内容は以下の少しだけです: | ||
==== | ==== 直定数「%」を「%%」としてエスケープする ==== | ||
言語ストリングにパーセンテージ文字 (%) を表示したい場合、あなたは代わりに2文字のパーセント (%%) でエスケープする必要があります。 | 言語ストリングにパーセンテージ文字 (%) を表示したい場合、あなたは代わりに2文字のパーセント (%%) でエスケープする必要があります。 | ||
< | <syntaxhighlight lang="php"> | ||
$string['onehundredpercentcorrect'] = 'あなたは 100%% 正しい!'; | $string['onehundredpercentcorrect'] = 'あなたは 100%% 正しい!'; | ||
</ | </syntaxhighlight> | ||
==== あなたはほとんどのプレースホルダに「%s」を使用できます ==== | ==== あなたはほとんどのプレースホルダに「%s」を使用できます ==== | ||
Line 159: | Line 157: | ||
あなたがプレースホルダを使用した言語ストリングを記述している場合、多くの場合、sprintf()に値をストリングとしてフォーマットするように伝える「%s」で切り抜けられます。PHPはほとんどの値を適切にオートキャストします。 | あなたがプレースホルダを使用した言語ストリングを記述している場合、多くの場合、sprintf()に値をストリングとしてフォーマットするように伝える「%s」で切り抜けられます。PHPはほとんどの値を適切にオートキャストします。 | ||
< | <syntaxhighlight lang="php"> | ||
$string['mynameis'] = 'こんにちは、私の名前は %s です!'; | $string['mynameis'] = 'こんにちは、私の名前は %s です!'; | ||
</ | </syntaxhighlight> | ||
==== 小数点のプレースホルダに関して ... ==== | ==== 小数点のプレースホルダに関して ... ==== | ||
Line 167: | Line 165: | ||
この場合、あなたは「%」の後に「.」を続けて小数点以下を「F」にできます。 | この場合、あなたは「%」の後に「.」を続けて小数点以下を「F」にできます。 | ||
< | <syntaxhighlight lang="php"> | ||
$string['twodecimalpoints'] = 'この数字には小数点以下2桁あります: %.2F'; | $string['twodecimalpoints'] = 'この数字には小数点以下2桁あります: %.2F'; | ||
$string['threedecimalpoints'] = 'この数字には小数点以下3桁あります: %.3F'; | $string['threedecimalpoints'] = 'この数字には小数点以下3桁あります: %.3F'; | ||
</ | </syntaxhighlight> | ||
多くの場合、これをPHP側のみで処理した方がエラーの発生は少ないように思えますが。つまり、10進数をget_string()に渡すのではなく、 スクリプトで数値を丸めたり整形したりして文字列にキャストした後、その整形済み数値の文字列をget_string()に送信してください。 | 多くの場合、これをPHP側のみで処理した方がエラーの発生は少ないように思えますが。つまり、10進数をget_string()に渡すのではなく、 スクリプトで数値を丸めたり整形したりして文字列にキャストした後、その整形済み数値の文字列をget_string()に送信してください。 | ||
Line 181: | Line 179: | ||
** アーティファクトに属するblocktypeのようなサブプラグインは<tt>{$cfg->dirroot}/artefact/{pluginname}/blocktype/{blockname}/lang/en.utf8/blocktype.{blockname}.php</tt>のように配置されます。また、セクションは「blocktype.{blockname}」のようになります。 | ** アーティファクトに属するblocktypeのようなサブプラグインは<tt>{$cfg->dirroot}/artefact/{pluginname}/blocktype/{blockname}/lang/en.utf8/blocktype.{blockname}.php</tt>のように配置されます。また、セクションは「blocktype.{blockname}」のようになります。 | ||
* '''テーマ''' 言語ファイルは<tt>$cfg>->dirroot/theme/{themename}/lang/en.utf8/theme.{themename}.php</tt>のように配置されます。 | * '''テーマ''' 言語ファイルは<tt>$cfg>->dirroot/theme/{themename}/lang/en.utf8/theme.{themename}.php</tt>のように配置されます。 | ||
** get_string()をコールする場合の「セクション」は「theme.{themename}」です。例えば次のようになります: | ** get_string()をコールする場合の「セクション」は「theme.{themename}」です。例えば次のようになります: 「theme.raw」, 「theme.primaryschool」 | ||
* '''外国語''' 言語パックはあなたのdatarootディレクトリにインストールされます: <tt>$cfg->dataroot/langpacks/{langcode}</tt> | * '''外国語''' 言語パックはあなたのdatarootディレクトリにインストールされます: <tt>$cfg->dataroot/langpacks/{langcode}</tt> | ||
** {langcode} は言語コードです。例えば次のようになります: 「pt.utf8」, 「es.utf8」, 「en_US.utf8」 | |||
** {langcode} は言語コードです。例えば次のようになります: | |||
* '''ローカル''' 言語ファイルは<tt>$cfg->dirroot/local/lang/{langcode}/{section}.php</tt>配下に配置されます。 | * '''ローカル''' 言語ファイルは<tt>$cfg->dirroot/local/lang/{langcode}/{section}.php</tt>配下に配置されます。 | ||
=== 翻訳 === | === 翻訳 === | ||
このシステムの最大のポイントはMaharaを翻訳できるようにすることです。詳細は「言語パック」ドキュメンテーションをご覧ください。基本的にはあなたがlangpacks.mahara.orgからダウンロードした言語パックを展開して「$cfg->dataroot/langpacks/ | このシステムの最大のポイントはMaharaを翻訳できるようにすることです。詳細は「言語パック」ドキュメンテーションをご覧ください。基本的にはあなたがlangpacks.mahara.orgからダウンロードした言語パックを展開して「$cfg->dataroot/langpacks/」ディレクトリ内に入れてください。ユーザのログイン画面に言語選択メニューが表示されます。 | ||
もし、特定の言語ストリングが言語パックに存在しない場合、言語が指定した親言語パックがインストールされていない限り、Maharaコアの英語言語ストリングが使用されます。 | もし、特定の言語ストリングが言語パックに存在しない場合、言語が指定した親言語パックがインストールされていない限り、Maharaコアの英語言語ストリングが使用されます。 | ||
Line 205: | Line 201: | ||
** 言語パックがPOフォーマットが変換された場合、また、あなたが「Plural-Forms:」ヘッダを入れている場合、これらの値は自動的に生成されます。 | ** 言語パックがPOフォーマットが変換された場合、また、あなたが「Plural-Forms:」ヘッダを入れている場合、これらの値は自動的に生成されます。 | ||
** '''pluralfunction''': 与えられたカウントに対してどの複数形ルールを使用すべきかを示すPHP関数名です。この関数は正確に1つの整数の引数 (アイテム数) を取得してどの複数形を使用すべきかを示すキーを返します。例えば英語の場合、ルールはカウントが1の場合「0」、それ以外の場合「1」を返します。言語のすべての言語ファイルは複数の文字列を配列として定義します。この配列では関数が返せる可能性のあるそれぞれのキーに対応する値を持つこととなります。 | ** '''pluralfunction''': 与えられたカウントに対してどの複数形ルールを使用すべきかを示すPHP関数名です。この関数は正確に1つの整数の引数 (アイテム数) を取得してどの複数形を使用すべきかを示すキーを返します。例えば英語の場合、ルールはカウントが1の場合「0」、それ以外の場合「1」を返します。言語のすべての言語ファイルは複数の文字列を配列として定義します。この配列では関数が返せる可能性のあるそれぞれのキーに対応する値を持つこととなります。 | ||
** '''pluralrule''': | ** '''pluralrule''': pluralfunctionに相当するJavaScriptの関数です。これは変数「n」に格納されている整数を評価および「n」を引数として受け取った場合の複数関数と全く同じ値を返すJavaScriptのスニペットである必要があります。 | ||
=== /localのカスタム言語ストリング === | === /localのカスタム言語ストリング === | ||
「/local」ディレクトリのカスタム言語ストリング | |||
多くのMaharaインストレーションではいくつかの言語ストリングのみ上書きしたい場合もあることでしょう。最も簡単なのは「/local」ディレクトリにカスタム言語ファイルを作成する方法です。カスタム言語ファイルが存在する場合、これらのファイルのストリングはコアの言語ファイルまたは言語パックの言語ファイルのストリングに優先されます。 | |||
カスタム言語ファイルではオーバーライド対象の言語を100%翻訳する必要はありません。あなたが実際にオーバーライドしたいストリングのみカスタム言語ファイルに含めます。 | |||
''' | '''例:''' | ||
< | <syntaxhighlight lang="php"> | ||
<?php | <?php | ||
// This file lives under /var/www/mahara/local/lang/en.utf8/mahara.php | // This file lives under /var/www/mahara/local/lang/en.utf8/mahara.php | ||
Line 223: | Line 219: | ||
$string['yes'] = 'Yessir!'; | $string['yes'] = 'Yessir!'; | ||
$string['login'] = 'Sign in!"; | $string['login'] = 'Sign in!"; | ||
</ | </syntaxhighlight> | ||
あなたは外国語ファイルおよびプラグイン言語ファイルを「local/lang」にも配置できます。以下すべて可能です: | |||
* local/lang/en.utf8/mahara.php | * local/lang/en.utf8/mahara.php | ||
Line 232: | Line 228: | ||
* local/lang/mi.utf8/theme.primaryschool.php | * local/lang/mi.utf8/theme.primaryschool.php | ||
=== | === 翻訳の連結は好ましくありません === | ||
異なる言語では単語の順序が異なるため、可能な限り言語ストリングの連結は避けるべきです。言語ストリングのパラメータを使用するか、複数言語文字列を使用してください。 | |||
''' | '''悪い:''' | ||
< | <syntaxhighlight lang="php"> | ||
<?php | <?php | ||
// | // 英語では問題ありませんが、形容詞が名詞の後に続くべきスペイン語ではどうでしょう? | ||
$yellowdogstr = get_string('yellow') . " " . get_string('dog'); | $yellowdogstr = get_string('yellow') . " " . get_string('dog'); | ||
$greendogstr = get_string('green') . " " . get_string('dog'); | $greendogstr = get_string('green') . " " . get_string('dog'); | ||
</ | </syntaxhighlight> | ||
''' | '''良い:''' | ||
< | <syntaxhighlight lang="php"> | ||
<?php | <?php | ||
// | // 英語: $string['coloreddog'] = '%s dog'; | ||
// | // 英語: $string['coloreddog'] = 'perro %s'; | ||
$yellowdogstr = get_string('coloreddog', 'artefact.dog', get_string('yellow')); | $yellowdogstr = get_string('coloreddog', 'artefact.dog', get_string('yellow')); | ||
$greendogstr = get_string('coloreddog', 'artefact.dog', get_string('green')); | $greendogstr = get_string('coloreddog', 'artefact.dog', get_string('green')); | ||
</ | </syntaxhighlight> | ||
''' | '''最良:''' | ||
< | <syntaxhighlight lang="php"> | ||
<?php | <?php | ||
// | // 一部の言語では「yellow」と組み合わせられた場合に「dog」が変わったり、「dog」と組み合わせられた場合に「yellow」が変わります。 | ||
// 英語: $string['dogyellow'] = 'yellow dog'; | |||
// | // スペイン語: $string['dogyellow'] = 'perro amarillo'; | ||
// | // オーストラリア英語: $string['dogyellow'] = 'dingo'; | ||
// | |||
$yellowdogstr = get_string('dogyellow'); | $yellowdogstr = get_string('dogyellow'); | ||
$greendogstr = get_string('doggreen'); | $greendogstr = get_string('doggreen'); | ||
</ | </syntaxhighlight> | ||
そして、似たようなことですが、もちろん、単語のパーツを連結しないてください。 | |||
''' | '''悪い:''' | ||
< | <syntaxhighlight lang="php"> | ||
<?php | <?php | ||
$blogstr = get_string('blog', 'artefact.blog'); | $blogstr = get_string('blog', 'artefact.blog'); | ||
$pluralblog = get_string('blog', 'artefact.blog') . get_string('s'); | $pluralblog = get_string('blog', 'artefact.blog') . get_string('s'); | ||
</ | </syntaxhighlight> | ||
''' | '''良い:''' | ||
< | <syntaxhighlight lang="php"> | ||
<?php | <?php | ||
$blogstr = get_string('blog', 'artefact.blog'); | $blogstr = get_string('blog', 'artefact.blog'); | ||
$pluralblog = get_string('blogs', 'artefact.blog'); | $pluralblog = get_string('blogs', 'artefact.blog'); | ||
// | // また、ブログの数が決まっている場合、複数ストリングのAPIを使用してください。 | ||
$numblogs = get_blog_count(); | $numblogs = get_blog_count(); | ||
$blogstr = get_string('nblogs', 'artefact.blog', $numblogs); | $blogstr = get_string('nblogs', 'artefact.blog', $numblogs); | ||
</ | </syntaxhighlight> | ||
この方法には言語ストリングが増えてしまうという欠点がありますが、残念ながら、文法が大きく異なる言語間で美しく翻訳をするにはこの方法しかありません。 | |||
=== | === あなたの言語ファイルをアルファベット順にする === | ||
実装上の観点からlangファイル内での言語ストリングの順序は問題ではありません。しかし、人間の読みやすさの観点から識別子のアルファベット順に並ぶべきです。 | |||
多くの開発者は機能別にグループ化したくなりますが、機能別にグループ化しても分類方法を無視した新しい文字列が追加された場合、やがて破綻してしまいます。最終的な結果はどの特定の言語ストリングもどの場所にもあり得る完全に無秩序なファイルです。これがMaharaコアのほとんどの言語ファイルの状態です。 | |||
そのため、新しい言語ファイルを作成する場合、言語文字列をアルファベット順に並べてください。もし、あなたが関連する文字列を隣り合わせになるようにしたい場合、タイプ別に分類した名前をつけてください。 | |||
< | 悪い: | ||
<syntaxhighlight lang="php"> | |||
<?php | <?php | ||
// Strings are sorta grouped together by functionality, in semi-random order | // Strings are sorta grouped together by functionality, in semi-random order | ||
Line 327: | Line 324: | ||
$string['youhaveoneblog'] = 'You have 1 journal.'; | $string['youhaveoneblog'] = 'You have 1 journal.'; | ||
$string['youhaveblogs'] = 'You have %s journals.'; | $string['youhaveblogs'] = 'You have %s journals.'; | ||
</ | </syntaxhighlight> | ||
良い: | |||
< | <syntaxhighlight lang="php"> | ||
<?php | <?php | ||
// Strings are in alphabetical order by identifier | // Strings are in alphabetical order by identifier | ||
Line 355: | Line 352: | ||
$string['youhavenoblogs'] = 'You have no journals.'; | $string['youhavenoblogs'] = 'You have no journals.'; | ||
$string['youhaveoneblog'] = 'You have 1 journal.'; | $string['youhaveoneblog'] = 'You have 1 journal.'; | ||
</ | </syntaxhighlight> | ||
=== | === 言語ストリング変更時に翻訳者に知らせる === | ||
言語ストリングの内容を大幅に変更した場合、言語ストリングの名称も変更してください。通常、私たちはこれを文字列の後に数字を置く (または増加させる) ことで対応しています。 | |||
この理由はLaunchpadの翻訳インターフェースではストリングの英語版変更時に翻訳者には通知されないからです。言語ストリングの名称を変更することにより、翻訳されていない新しいストリングとして翻訳者にその存在を知らせることができます。 | |||
前: | |||
< | <syntaxhighlight lang="php"> | ||
$string['namedesc'] = 'The original version of the string.'; | $string['namedesc'] = 'The original version of the string.'; | ||
</ | </syntaxhighlight> | ||
後: | |||
< | <syntaxhighlight lang="php"> | ||
$string['namedesc1'] = 'The new version of the string, with content that should be reflected in all langpacks.'; | $string['namedesc1'] = 'The new version of the string, with content that should be reflected in all langpacks.'; | ||
</ | </syntaxhighlight> | ||
また、このストリングが使用されているPHPファイルおよびテンプレートのストリング名も必ず更新してください。 | |||
=== | === ヘルプファイル === | ||
ヘルプファイルは特殊なタイプの言語ファイルです。これはユーザがヘルプボタンをクリックしたときにポップアップするHTMLスニペット (基本的には<body>タグ内のコンテンツ) です。 | |||
いくつかの異なる方法でヘルプファイルを追加できます。主なものは以下のとおりです: | |||
==== | ==== Pieformsヘルプファイル ==== | ||
一般的にはpieform要素定義に「'help'=>true」を追加して作成します。そして、Pieformsは「help/forms/{formname}.{elementname}.html」という名称のヘルプファイルをポップアップするためのコードを自動的に追加します。フォームに「pluginname」および「plugintype」フィールドがある場合、Pieformsはプラグインの言語ディレクトリ配下のヘルプファイルを探します。 | |||
''' | '''例:''' | ||
< | <syntaxhighlight lang="php"> | ||
// | // 「下書き」チェックボックスにはフォーム名「name」、「plugintype」「pluginname」および要素名をもとにディレクトリ「artefact/blog/lang/en.utf8/help/form/editpost.draft.html」にヘルプファイルがあります。 | ||
$form = pieform(array( | $form = pieform(array( | ||
'name' => 'editpost', | 'name' => 'editpost', | ||
Line 404: | Line 399: | ||
) | ) | ||
); | ); | ||
</ | </syntaxhighlight> | ||
==== | ==== ページヘルプファイル ==== | ||
ページ自体にもヘルプファイルを付加できます。ページに「SECTION_PAGE」「SECTION_PLUGINNAME」「SECTION_PLUGINTYPE」の各定数が正しく定義されている場合、smarty()によるページテンプレート設定時に「has_help_file()」関数を呼び出して「help/pages/{SECTION_PAGE}.html」にヘルプファイルが存在するかどうかチェックします。ヘルプファイルが存在する場合、ページタイトルの横にヘルプボタンが表示されます。SECTION_PLUGINNAMEおよびSECTION_PLUGINTYPEが提供された場合、プラグインのlangディレクトリ配下にあるヘルプファイルを探します。 | |||
''' | '''例:''' | ||
< | <syntaxhighlight lang="php"> | ||
<?php | <?php | ||
// Help file will be artefact/blog/lang/en.utf8/help/page/view.html | // Help file will be artefact/blog/lang/en.utf8/help/page/view.html | ||
Line 418: | Line 413: | ||
define('SECTION_PLUGINNAME', 'blog'); | define('SECTION_PLUGINNAME', 'blog'); | ||
define('SECTION_PAGE', 'view'); | define('SECTION_PAGE', 'view'); | ||
</ | </syntaxhighlight> | ||
[[開発者エリア/ページトップ定数]]もご覧ください。 | |||
==== | ==== セクションヘルプファイル ==== | ||
ページセクションにもヘルプファイルを付加できます。これらはlangディレクトリ配下の「help/sections/」ディレクトリ内にあります。ヘルプファイルは「contextualhelp」dwooタグを使用して呼び出されます。 | |||
''' | '''例:''' | ||
< | <syntaxhighlight lang="smarty"> | ||
<!-- | <!-- ヘルプファイルは「lang/en.utf8/help/sections/activitytpeselect.html」となります。 | ||
これは「plugintype='core' --> | |||
{contextualhelp plugintype='core' pluginname='activity' section='activitytypeselect'} | {contextualhelp plugintype='core' pluginname='activity' section='activitytypeselect'}」を理由としてコアlangディレクトリ配下に置かれることに留意してください。 | ||
</ | </syntaxhighlight> | ||
==== その他 | ==== その他? ==== | ||
TODO: | TODO: ヘルプファイルを呼び出す方法は他にもあるのでしょうか? ヘルプアイコンを生成する関数を呼べば良いのでしょうか? | ||
==== localのカスタムヘルプファイル ==== | ==== localのカスタムヘルプファイル ==== | ||
* '''Core''' | ヘルプファイルは/localディレクトリ内でオーバーライドできます。 | ||
** | |||
* '''Plugin''' | * '''Core''' ヘルプファイルは<tt>local/lang/en.utf8/help/{forms|pages|sections}/{filename}.html</tt>配下に設置されます。 | ||
** | ** 例: <tt>local/lang/en.utf8/help/forms/adduser.friendscontrol.html</tt> | ||
* '''Plugin''' ヘルプファイルは<tt>/local/lang/en.utf8/help/{forms|pages|sections}/{plugintype}.{pluginname}.{filename}.html</tt>配下に設置されます。 | |||
** 例: <tt>local/lang/en.utf8/help/forms/artefact.blog.addentry.draft.html</tt> | |||
=== ストリングを変更できない場合のトラブルシューティング === | |||
あなたは開発またはローカルカスタマイゼーションのためにいくつかの言語ストリングを変更しようとしています。あなたは変更をファイルに保存してページをリロードしましたが、ストリングは変更されていません。以下、考えられるいくつかの原因です: | |||
==== キャッシュ済みストリング ==== | |||
Mahara 15.10から、Maharaはナビゲーションメニュー (いくつかの翻訳された言語文字列を含む) をデータベースにキャッシュしています。Mahara 16.10以降、これらのキャッシュされた言語ストリングをリセットするため、管理画面の「キャッシュをクリアする」ボタンまたはCLIスクリプトの<tt>htdocs/admin/cli/clear_caches.php</tt>を使用できます。 | |||
Mahara 15.10および16.04において「キャッシュをクリア」するボタンは実装されていません。あなたは次善策としてとして「管理」→「サイト設定」でページ下部の「変更を保存」ボタンをクリックしてキャッシュをクリアできます。これにより実際に変更を加えたかどうかにかかわらずキャッシュがクリアされます。あなたは別の方法として<tt>htdocs/local/version.php</tt>のバージョン番号を上げるためのアップグレードをキャッシュクリアのトリガーにできます。 | |||
==== ユーザデータフィールドにコピーされたデフォルトストリング ==== | |||
Maharaのいくつかの言語ストリングはユーザが編集可能なデータフィールドにコピーするためのデフォルト値として使用されます。例えば「管理 -> サイトページ」上のテキストは言語ストリングから生成されますが、管理者が編集した場合、データベースに保存されます。このようなケースではオリジナルの言語ストリングを修正しても、保存されているユーザデータフィールドは更新されません。 | |||
==== | ==== 正しいストリングが見つかりませんでした ==== | ||
いくつかの単語およびフレーズは異なるファイル内で複数の言語ストリングとして記述されています。正しい言語ファイルに正しいストリングが含まれているか再度確認してください。また、コアの<tt>htdocs/lang</tt>ディレクトリだけでなく、プラグインのディレクトリ (<tt>artefact/annotation/lang/en.utf8</tt>等) も確認してください。 | |||
==== | ==== ハードコーディングされたストリング ==== | ||
翻訳のために言語ストリングを言語ファイルに移動するのではなく、PHPファイルまたはDwooテンプレートにハードコーディングされることはよくあるバグです。言語ストリングを変更できない場合、誤ってハードコーディングされていないか、言語ファイルの外を確認するのも良いかもしれません。 | |||
あなたがMahara標準ディストリビューションの一部のファイルにこの現象を発見した場合、Mahara launchpadプロジェクトにバグとして報告してください。あなたがサードパーティ製プラグインでこの現象を見つけた場合、プラグイン開発者にご連絡ください。 |
Latest revision as of 13:54, 19 April 2022
国際化 (i18n) およびローカライゼーション (l10n) の目的のため、Maharaでユーザに表示されるストリングすべてはコードに直接記述されるのではなく、「言語ストリング」に保存された上でget_string($identifier, $section)関数により表示されます。この関数は外国語の言語パックがインストールされているか確認します。また、カスタム言語ファイルが存在するか確認して存在する場合、そのストリングを使用します。そうでない場合、コア言語ファイルに戻ります。
PHPでのget_string()の使用方法
関数get_string()には以下のパラメータがあります:
- identifier: 言語ストリング名です。セクション内ではユニークです。identifierはPHP配列キーとして受け入れられるべきです。慣習により言語ストリング名は英語コンテンツと同じものであり、すべてスペースなしの半角英字です。ストリングの正確な表現の代わりにストリングの目的をストリング名として使用できます。
- section: 言語ストリングが存在するファイルです。これは技術的に任意です。無視された場合、多くの一般的なコアストリングを含むデフォルトの「mahara」セクションが割り当てられます。
- 例:
- admin: コアの「admin」セクション用です。
- artefact.blog: 「blog」アーティファクトプラグイン用です。
- theme.primaryschool: 「primaryschool」テーマ用です。
- 例:
- params: (任意) 言語ストリングには1つまたはそれ以上のsprintf()パラメータを含めます。言語ストリング内に存在する場合、get_string()がコールされて使用するストリングを配置するためにパラメータ値との合致が要求されます。パラメータは異なる語順の言語への翻訳時に役立ちます。
例:
$yesstr = get_string('yes'); // lang/en.utf8/mahara.php
$clamstr = get_string('pathtoclam', 'admin'); // lang/en.utf8/admin.php
$blogstr = get_string('blog', 'artefact.blog'); // artefact/blog/lang/en.utf8/artefact.blog.php
$copyrightstr = get_string('feedrights','artefact.blog', $USER->displayname); // パラメータ付き言語ストリング
// 複数形ストリング。最初の変数は複数形アイテムの数です。get_stringは単一または複数のどちらを使うか決定するために変数を使用します (英語以外の言語では2つ以上の複数形が存在する場合があります)。
$updatefilesstr = get_string('updatednfiles', 'mahara', 5);
Dwooテンプレートからの言語ストリング使用方法
あなたは {} タグを使ってDwoテンプレート内部から言語ストリングにもアクセスできます:
{str tag='identifier' section='section' arg1='first param value' arg2='second param value'}
これを動作させるコードは次のとおりです: htdocs/lib/dwoo/mahara/plugins/function.str.php
JavaScriptからの言語ストリングの使用方法
プリフェッチ
あなたはJavaScriptにも言語ストリングを使用できます。最初にsmarty()関数に$pagestrings変数を渡して言語ストリングを読み込んでください ...
// Providing a $pagestrings variable to smarty()
$pagestrings = array(
'admin' => array(
'discardpageedits',
'pathtoclam'
),
'mahara' => array('yes')
);
... そして、次にJavaScriptのget_string()関数を使用して言語ストリングにアクセスできます。これは「section」セクションを除外する以外、PHPのget_string()に似ています (注意: これはあなたが2つの言語ストリングを同じIDで異なるセクションに含めないことを意味します)。また、「%s」タイプの置換パラメータのみ受け付けます。
<script type="text/javascript">
alert(get_string('yes'));
confirm(get_string('discardpageedits', 'first param value'));
</script>
特定のJavaScriptファイルがDwooに含まれる場合にJavaScriptのget_string()で多くのJavaScriptストリングを常に使用できるようハードコードされています。このリストに関して「htdocs/lib/web.php」の関数「jsstrings」をご覧ください。
AJAX経由で動的に取得する
Mahara 15.10現在、あなたはAjax経由で動的に言語ストリングを取得できます。get_string_ajax()関数を使用してください。事前に取得した言語ストリングとは異なり、動的に取得したストリングにはセクションパラメータおよび他のパラメータを含めます。この機能はget_string_ajax()リクエストごとの結果をキャッシュします。
この関数は非同期に動作するため、alert()およびconfirm()のコールには適していません。関数自体はユニークIDを含む<span>タグのプレースホルダを返します。プレースホルダはAJAXコールが戻った際に評価されたストリングと置換されます。そのため、あなたが直接alert()、confirm()またはその他の即時出力メソッドを使用する場合、ユーザには結果のストリングではなく、プレースホルダが表示されます。
<script type="text/javascript">
// 正解! ページのHTMLに戻り値を挿入します
var noresults = get_string_ajax('noresultsfound', 'mahara');
jQuery('#notice').html('<p class="no-results">' + noresults + '</p>');
// 不正解! あなたのユーザの警告ボックスに「<span id="str790709789087"></span>」が表示されます。
alert(get_string_ajax('cannotremove', 'auth'));
</script>
言語ファイルの構造
言語ファイルは{section}.phpのように名前付けされます。ここでの「section」はセクション値としてget_string()に渡されます。これには「$string」と呼ばれる配列にキーを追加するための一連の行が含まれます。すべてのMaharaライブラリファイルのようにウェブブラウザからのアクセスを防ぐため、内部定数のチェックから始めてください。
<?php
defined('INTERNAL') || die();
$string['changepassworddesc'] = '新しいパスワード';
$string['changepasswordotherinterface'] = 'あなたは異なるインターフェースでパスワードを変更できます。 ';
$string['oldpasswordincorrect'] = 'これはあなたの現在のパスワードではありません。';
// 複数形ストリングです。英語では単数形はキー「0」にマップしてください。他の言語ではlangconfig.php内のpluralfunctionで定義しているキーにマップしてください。
$string['updatednfiles'] = array(
0 => 'あなたは %s ファイルを更新しました。',
1 => 'あなたは %s ファイルを更新しました。',
);
複数形ストリング
正確には加算可能ストリングと読んだ方が良いのかもしれません。英語には2つの複数形があります: 単数形 (1つ) および複数形 (2つ以上)。他の言語には複数の複数形があります。例えばスロベニア語の場合、あなたが1つ、2つまたは3つ以上を持つかにより単語の語尾が異なる2通りの複数形があります。
英語とは異なる複数形を持つ言語を翻訳できるようにしたい場合、「あなたには 3 つのブログがあります/あなたには 1 つのブログがあります」のように数字でカウントできる特別な構文のストリングがあります。
まず、get_string()を使用する場合、第1カスタムパラメータとしてストリングのアイテムカウント数を渡してください:
get_string('fileattachedportfolioitems', 'artefact.file', $numitems);
次に言語ファイルでストリング配列を作成してください。英語の場合、キーが「0」の配列のアイテムは単数形のストリング、キーが「1」の配列のアイテムは複数形となります。
$string['fileattachedtoportfolioitems'] = array(
0 => 'このファイルはあなたのポートフォリオの 1 の他のアイテムに添付されています。',
1 => 'このファイルはあなたのポートフォリオの %s の他のアイテムに添付されています。',
);
この構文により、英語とは異なる複数形を持つ他の言語を実装できます。それぞれの言語にはどのキーがカウント数を返すか決定するpluralfunction関数を含むlangconfig.phpファイルがあります。英語では単数形に「0」、複数形に「1」を返します。恐らく、他の言語はさらに多いまたは少ないキーを返すと思われます。そのため、別の言語パックの同じストリングは以下のようになります:
$string['fileattachedtoportfolioitems'] = array(
0 => 'Ta datoteka je pripeta k %s drugemu elementu v vašem listovniku.',
1 => 'Ta datoteka je pripeta k %s drugima elementoma v vašem listovniku.',
2 => 'Ta datoteka je pripeta k %s drugim elementom v vašem listovniku.',
3 => 'Ta datoteka je pripeta k %s drugim elementom v vašem listovniku.',
);
詳細はLanguage Packs/Plural formsおよび https://bugs.launchpad.net/mahara/+bug/901051 をご覧ください。
カウンタパラメータは最初のパラメータにしてください。あなたがカウンタパラメータをストリングの最初に表示したくない場合、sprintf位置指定子で移動してください:
$string['setprobationpoints'] = array(
0 => 'Set probation points to %2$d for %1$d user.',
1 => 'Set probation points to %2$d for %1$d users.';
);
メモ: Maharaにはこのフォーマットに従わない古い複数形ストリングが相当数含まれます。あなたが古い複数形ストリングを見つけた時に直してくれると助かります。翻訳者に分かりやすくするため、正しいストリングには古いストリングとは異なるストリング名を使用してください。あなたが古いストリングのすべての参照を削除できた場合のみ、古いストリングを削除してください。
Mahara言語ストリングはsprintf()フォーマットストリングです
私たちが「%s」をプレースホルダとして使用する理由はMahara言語ストリングが表示前にPHPのsprintf()関数で渡されるからです。言い換えれば、Mahara言語ストリングは実際にはsprintf()フォーマットストリングです!
詳細なsprintf()フォーマット文法はここで確認できますが、あなたが知る必要のある内容は以下の少しだけです:
直定数「%」を「%%」としてエスケープする
言語ストリングにパーセンテージ文字 (%) を表示したい場合、あなたは代わりに2文字のパーセント (%%) でエスケープする必要があります。
$string['onehundredpercentcorrect'] = 'あなたは 100%% 正しい!';
あなたはほとんどのプレースホルダに「%s」を使用できます
あなたがプレースホルダを使用した言語ストリングを記述している場合、多くの場合、sprintf()に値をストリングとしてフォーマットするように伝える「%s」で切り抜けられます。PHPはほとんどの値を適切にオートキャストします。
$string['mynameis'] = 'こんにちは、私の名前は %s です!';
小数点のプレースホルダに関して ...
「%s」を使用する主な例外はプレースホルダに小数を表示する必要がある場合で特に小数点以下の数を表示する必要がある場合です。 この場合、あなたは「%」の後に「.」を続けて小数点以下を「F」にできます。
$string['twodecimalpoints'] = 'この数字には小数点以下2桁あります: %.2F';
$string['threedecimalpoints'] = 'この数字には小数点以下3桁あります: %.3F';
多くの場合、これをPHP側のみで処理した方がエラーの発生は少ないように思えますが。つまり、10進数をget_string()に渡すのではなく、 スクリプトで数値を丸めたり整形したりして文字列にキャストした後、その整形済み数値の文字列をget_string()に送信してください。
言語ファイルはどこに?
- コア 言語ファイルは$cfg->dirroot/lang/en.utf8/{section}.phpのように配置されます。
- プラグイン 言語ファイルは$cfg->dirroot/{plugintype}/{pluginname}/lang/en.utf8/{plugintype}.{pluginname}.phpのように配置されます。
- プラグインをget_string()で呼び出す場合、プラグインの「セクション」は「{plugintype}.{pluginname}」のようになることに留意してください。例えば次のようになります: 「artefact.blog」「import.leap2a」「blocktype.contactinfo」
- アーティファクトに属するblocktypeのようなサブプラグインは{$cfg->dirroot}/artefact/{pluginname}/blocktype/{blockname}/lang/en.utf8/blocktype.{blockname}.phpのように配置されます。また、セクションは「blocktype.{blockname}」のようになります。
- テーマ 言語ファイルは$cfg>->dirroot/theme/{themename}/lang/en.utf8/theme.{themename}.phpのように配置されます。
- get_string()をコールする場合の「セクション」は「theme.{themename}」です。例えば次のようになります: 「theme.raw」, 「theme.primaryschool」
- 外国語 言語パックはあなたのdatarootディレクトリにインストールされます: $cfg->dataroot/langpacks/{langcode}
- {langcode} は言語コードです。例えば次のようになります: 「pt.utf8」, 「es.utf8」, 「en_US.utf8」
- ローカル 言語ファイルは$cfg->dirroot/local/lang/{langcode}/{section}.php配下に配置されます。
翻訳
このシステムの最大のポイントはMaharaを翻訳できるようにすることです。詳細は「言語パック」ドキュメンテーションをご覧ください。基本的にはあなたがlangpacks.mahara.orgからダウンロードした言語パックを展開して「$cfg->dataroot/langpacks/」ディレクトリ内に入れてください。ユーザのログイン画面に言語選択メニューが表示されます。
もし、特定の言語ストリングが言語パックに存在しない場合、言語が指定した親言語パックがインストールされていない限り、Maharaコアの英語言語ストリングが使用されます。
langconfig.php
言語には少ない量の設定データが含まれます。これはコア言語ファイル「langconfig.php」内にあります。以下の値は最も重要です:
- thislanguage: 言語の言語名です。これはユーザの言語選択メニューに表示されます。
- locale: この言語に合致するコンピュータのロケールストリング一覧です。これらがどのようなものであるかに関して他の言語パックを参照してください。
- parentlanguage: (任意) これが提供された場合、未翻訳のMaharaストリングは親言語の翻訳を探します (親言語がインストールされている場合)。
- pluralization:
- 詳細はストリングの複数形 (英語) APIをご覧ください。
- 言語パックがPOフォーマットが変換された場合、また、あなたが「Plural-Forms:」ヘッダを入れている場合、これらの値は自動的に生成されます。
- pluralfunction: 与えられたカウントに対してどの複数形ルールを使用すべきかを示すPHP関数名です。この関数は正確に1つの整数の引数 (アイテム数) を取得してどの複数形を使用すべきかを示すキーを返します。例えば英語の場合、ルールはカウントが1の場合「0」、それ以外の場合「1」を返します。言語のすべての言語ファイルは複数の文字列を配列として定義します。この配列では関数が返せる可能性のあるそれぞれのキーに対応する値を持つこととなります。
- pluralrule: pluralfunctionに相当するJavaScriptの関数です。これは変数「n」に格納されている整数を評価および「n」を引数として受け取った場合の複数関数と全く同じ値を返すJavaScriptのスニペットである必要があります。
/localのカスタム言語ストリング
「/local」ディレクトリのカスタム言語ストリング
多くのMaharaインストレーションではいくつかの言語ストリングのみ上書きしたい場合もあることでしょう。最も簡単なのは「/local」ディレクトリにカスタム言語ファイルを作成する方法です。カスタム言語ファイルが存在する場合、これらのファイルのストリングはコアの言語ファイルまたは言語パックの言語ファイルのストリングに優先されます。
カスタム言語ファイルではオーバーライド対象の言語を100%翻訳する必要はありません。あなたが実際にオーバーライドしたいストリングのみカスタム言語ファイルに含めます。
例:
<?php
// This file lives under /var/www/mahara/local/lang/en.utf8/mahara.php
defined('INTERNAL') || die();
$string['yes'] = 'Yessir!';
$string['login'] = 'Sign in!";
あなたは外国語ファイルおよびプラグイン言語ファイルを「local/lang」にも配置できます。以下すべて可能です:
- local/lang/en.utf8/mahara.php
- local/lang/en.utf8/blocktype.contactinfo.php
- local/lang/pt.utf8/artefact.blog.php
- local/lang/mi.utf8/theme.primaryschool.php
翻訳の連結は好ましくありません
異なる言語では単語の順序が異なるため、可能な限り言語ストリングの連結は避けるべきです。言語ストリングのパラメータを使用するか、複数言語文字列を使用してください。
悪い:
<?php
// 英語では問題ありませんが、形容詞が名詞の後に続くべきスペイン語ではどうでしょう?
$yellowdogstr = get_string('yellow') . " " . get_string('dog');
$greendogstr = get_string('green') . " " . get_string('dog');
良い:
<?php
// 英語: $string['coloreddog'] = '%s dog';
// 英語: $string['coloreddog'] = 'perro %s';
$yellowdogstr = get_string('coloreddog', 'artefact.dog', get_string('yellow'));
$greendogstr = get_string('coloreddog', 'artefact.dog', get_string('green'));
最良:
<?php
// 一部の言語では「yellow」と組み合わせられた場合に「dog」が変わったり、「dog」と組み合わせられた場合に「yellow」が変わります。
// 英語: $string['dogyellow'] = 'yellow dog';
// スペイン語: $string['dogyellow'] = 'perro amarillo';
// オーストラリア英語: $string['dogyellow'] = 'dingo';
$yellowdogstr = get_string('dogyellow');
$greendogstr = get_string('doggreen');
そして、似たようなことですが、もちろん、単語のパーツを連結しないてください。
悪い:
<?php
$blogstr = get_string('blog', 'artefact.blog');
$pluralblog = get_string('blog', 'artefact.blog') . get_string('s');
良い:
<?php
$blogstr = get_string('blog', 'artefact.blog');
$pluralblog = get_string('blogs', 'artefact.blog');
// また、ブログの数が決まっている場合、複数ストリングのAPIを使用してください。
$numblogs = get_blog_count();
$blogstr = get_string('nblogs', 'artefact.blog', $numblogs);
この方法には言語ストリングが増えてしまうという欠点がありますが、残念ながら、文法が大きく異なる言語間で美しく翻訳をするにはこの方法しかありません。
あなたの言語ファイルをアルファベット順にする
実装上の観点からlangファイル内での言語ストリングの順序は問題ではありません。しかし、人間の読みやすさの観点から識別子のアルファベット順に並ぶべきです。
多くの開発者は機能別にグループ化したくなりますが、機能別にグループ化しても分類方法を無視した新しい文字列が追加された場合、やがて破綻してしまいます。最終的な結果はどの特定の言語ストリングもどの場所にもあり得る完全に無秩序なファイルです。これがMaharaコアのほとんどの言語ファイルの状態です。
そのため、新しい言語ファイルを作成する場合、言語文字列をアルファベット順に並べてください。もし、あなたが関連する文字列を隣り合わせになるようにしたい場合、タイプ別に分類した名前をつけてください。
悪い:
<?php
// Strings are sorta grouped together by functionality, in semi-random order
$string['baseline'] = 'Baseline';
$string['top'] = 'Top';
$string['middle'] = 'Middle';
$string['bottom'] = 'Bottom';
$string['texttop'] = 'Text top';
$string['textbottom'] = 'Text bottom';
$string['left'] = 'Left';
$string['right'] = 'Right';
$string['src'] = 'Image URL';
$string['image_list'] = 'Attached image';
$string['alt'] = 'Description';
$string['copyfull'] = 'Others will get their own copy of your %s';
$string['copyreference'] = 'Others may display your %s in their page';
$string['copynocopy'] = 'Skip this block entirely when copying the page';
$string['viewposts'] = 'Copied entries (%s)';
$string['postscopiedfromview'] = 'Entries copied from %s';
$string['youhavenoblogs'] = 'You have no journals.';
$string['youhaveoneblog'] = 'You have 1 journal.';
$string['youhaveblogs'] = 'You have %s journals.';
良い:
<?php
// Strings are in alphabetical order by identifier
// Strings with similar purposes have names that start with their purpose and then a
// description, so that they wind up next to each other alphabetically
$string['copyfull'] = 'Others will get their own copy of your %s';
$string['copynocopy'] = 'Skip this block entirely when copying the page';
$string['copyreference'] = 'Others may display your %s in their page';
$string['imagealt'] = 'Description';
$string['imagelist'] = 'Attached image';
$string['imagesrc'] = 'Image URL';
$string['positionbaseline'] = 'Baseline';
$string['positionbottom'] = 'Bottom';
$string['positionleft'] = 'Left';
$string['positionmiddle'] = 'Middle';
$string['positionright'] = 'Right';
$string['positiontextbottom'] = 'Text bottom';
$string['positiontexttop'] = 'Text top';
$string['positiontop'] = 'Top';
$string['postscopiedfromview'] = 'Entries copied from %s';
$string['viewposts'] = 'Copied entries (%s)';
$string['youhaveblogs'] = 'You have %s journals.';
$string['youhavenoblogs'] = 'You have no journals.';
$string['youhaveoneblog'] = 'You have 1 journal.';
言語ストリング変更時に翻訳者に知らせる
言語ストリングの内容を大幅に変更した場合、言語ストリングの名称も変更してください。通常、私たちはこれを文字列の後に数字を置く (または増加させる) ことで対応しています。
この理由はLaunchpadの翻訳インターフェースではストリングの英語版変更時に翻訳者には通知されないからです。言語ストリングの名称を変更することにより、翻訳されていない新しいストリングとして翻訳者にその存在を知らせることができます。
前:
$string['namedesc'] = 'The original version of the string.';
後:
$string['namedesc1'] = 'The new version of the string, with content that should be reflected in all langpacks.';
また、このストリングが使用されているPHPファイルおよびテンプレートのストリング名も必ず更新してください。
ヘルプファイル
ヘルプファイルは特殊なタイプの言語ファイルです。これはユーザがヘルプボタンをクリックしたときにポップアップするHTMLスニペット (基本的には<body>タグ内のコンテンツ) です。
いくつかの異なる方法でヘルプファイルを追加できます。主なものは以下のとおりです:
Pieformsヘルプファイル
一般的にはpieform要素定義に「'help'=>true」を追加して作成します。そして、Pieformsは「help/forms/{formname}.{elementname}.html」という名称のヘルプファイルをポップアップするためのコードを自動的に追加します。フォームに「pluginname」および「plugintype」フィールドがある場合、Pieformsはプラグインの言語ディレクトリ配下のヘルプファイルを探します。
例:
// 「下書き」チェックボックスにはフォーム名「name」、「plugintype」「pluginname」および要素名をもとにディレクトリ「artefact/blog/lang/en.utf8/help/form/editpost.draft.html」にヘルプファイルがあります。
$form = pieform(array(
'name' => 'editpost',
'plugintype' => 'artefact',
'pluginname' => 'blog',
'elements' => array(
'draft' => array(
'type' => 'checkbox',
'title' => get_string('draft', 'artefact.blog'),
'description' => get_string('thisisdrafdesc', 'artefact.blog'),
'help' => true
)
)
);
ページヘルプファイル
ページ自体にもヘルプファイルを付加できます。ページに「SECTION_PAGE」「SECTION_PLUGINNAME」「SECTION_PLUGINTYPE」の各定数が正しく定義されている場合、smarty()によるページテンプレート設定時に「has_help_file()」関数を呼び出して「help/pages/{SECTION_PAGE}.html」にヘルプファイルが存在するかどうかチェックします。ヘルプファイルが存在する場合、ページタイトルの横にヘルプボタンが表示されます。SECTION_PLUGINNAMEおよびSECTION_PLUGINTYPEが提供された場合、プラグインのlangディレクトリ配下にあるヘルプファイルを探します。
例:
<?php
// Help file will be artefact/blog/lang/en.utf8/help/page/view.html
define('SECTION_PLUGINTYPE', 'artefact');
define('SECTION_PLUGINNAME', 'blog');
define('SECTION_PAGE', 'view');
開発者エリア/ページトップ定数もご覧ください。
セクションヘルプファイル
ページセクションにもヘルプファイルを付加できます。これらはlangディレクトリ配下の「help/sections/」ディレクトリ内にあります。ヘルプファイルは「contextualhelp」dwooタグを使用して呼び出されます。
例:
<!-- ヘルプファイルは「lang/en.utf8/help/sections/activitytpeselect.html」となります。
これは「plugintype='core' -->
{contextualhelp plugintype='core' pluginname='activity' section='activitytypeselect'}」を理由としてコアlangディレクトリ配下に置かれることに留意してください。
その他?
TODO: ヘルプファイルを呼び出す方法は他にもあるのでしょうか? ヘルプアイコンを生成する関数を呼べば良いのでしょうか?
localのカスタムヘルプファイル
ヘルプファイルは/localディレクトリ内でオーバーライドできます。
- Core ヘルプファイルはlocal/lang/en.utf8/help/{forms|pages|sections}/{filename}.html配下に設置されます。
- 例: local/lang/en.utf8/help/forms/adduser.friendscontrol.html
- Plugin ヘルプファイルは/local/lang/en.utf8/help/{forms|pages|sections}/{plugintype}.{pluginname}.{filename}.html配下に設置されます。
- 例: local/lang/en.utf8/help/forms/artefact.blog.addentry.draft.html
ストリングを変更できない場合のトラブルシューティング
あなたは開発またはローカルカスタマイゼーションのためにいくつかの言語ストリングを変更しようとしています。あなたは変更をファイルに保存してページをリロードしましたが、ストリングは変更されていません。以下、考えられるいくつかの原因です:
キャッシュ済みストリング
Mahara 15.10から、Maharaはナビゲーションメニュー (いくつかの翻訳された言語文字列を含む) をデータベースにキャッシュしています。Mahara 16.10以降、これらのキャッシュされた言語ストリングをリセットするため、管理画面の「キャッシュをクリアする」ボタンまたはCLIスクリプトのhtdocs/admin/cli/clear_caches.phpを使用できます。
Mahara 15.10および16.04において「キャッシュをクリア」するボタンは実装されていません。あなたは次善策としてとして「管理」→「サイト設定」でページ下部の「変更を保存」ボタンをクリックしてキャッシュをクリアできます。これにより実際に変更を加えたかどうかにかかわらずキャッシュがクリアされます。あなたは別の方法としてhtdocs/local/version.phpのバージョン番号を上げるためのアップグレードをキャッシュクリアのトリガーにできます。
ユーザデータフィールドにコピーされたデフォルトストリング
Maharaのいくつかの言語ストリングはユーザが編集可能なデータフィールドにコピーするためのデフォルト値として使用されます。例えば「管理 -> サイトページ」上のテキストは言語ストリングから生成されますが、管理者が編集した場合、データベースに保存されます。このようなケースではオリジナルの言語ストリングを修正しても、保存されているユーザデータフィールドは更新されません。
正しいストリングが見つかりませんでした
いくつかの単語およびフレーズは異なるファイル内で複数の言語ストリングとして記述されています。正しい言語ファイルに正しいストリングが含まれているか再度確認してください。また、コアのhtdocs/langディレクトリだけでなく、プラグインのディレクトリ (artefact/annotation/lang/en.utf8等) も確認してください。
ハードコーディングされたストリング
翻訳のために言語ストリングを言語ファイルに移動するのではなく、PHPファイルまたはDwooテンプレートにハードコーディングされることはよくあるバグです。言語ストリングを変更できない場合、誤ってハードコーディングされていないか、言語ファイルの外を確認するのも良いかもしれません。
あなたがMahara標準ディストリビューションの一部のファイルにこの現象を発見した場合、Mahara launchpadプロジェクトにバグとして報告してください。あなたがサードパーティ製プラグインでこの現象を見つけた場合、プラグイン開発者にご連絡ください。