r-labs

h1. 国際化

このプラグインを日本語に対応させるためには国際化する必要があります。

この国際化について説明します。

h2. 国際化

Rails の国際化には *i18n* というライブラリを使用します。 

国際化は英語でいうと internationalization で 18 文字なので、 i18n と略記されます。ライブラリはそのままの名前です。

英語以外の言語を使えるようにするためにはレベルがあります。 http://jp.rubyist.net/magazine/?0025-Ruby19_m17n#l2

|_. 名称   |_. 略号 |_. 説明 |

| 地域化 (localization) | L10N | マルチバイト文字を扱える |

| 国際化 (internationalization) | I18N | 各種メッセージや通貨記号等を地域ごとに容易に切り替えられる |

| 多言語化 (Multilingualization) | M17N | 同時に複数の言語を扱える |

Rails の i18n は国際化に対応していて、ユーザの言語環境の設定に応じて、メッセージの切り替えや日付などの表示形式を変えることが出来ます。

Ruby はバージョン 1.9 から m17n に対応しました。今のバージョンの Redmine は 1.9 に対応していませんが、 Ruby の m17n にはメッセージ切り替えの機能はありませんので、今後も i18n による国際化の方法は変わらないのではないかと思います。

h2. メッセージファイル

プラグインのスケルトン生成スクリプトでは config/locales/en.yml ファイルが生成されます。

*config/locales* が国際化用のメッセージファイルを置くディレクトリで、ここに言語別のメッセージファイルを置けば、ユーザの指定した言語のメッセージファイルの内容がラベルやメッセージとして使用されます。

生成された *en.yml* が英語用のファイルです。日本語用のメッセージファイル名は *ja.yml* となります。

日本語表示するだけならば ja.yml だけでもよいのですが、プラグインを公開する場合などは英語のメッセージも付けてください。英語は苦手だという方もいるかと思いますが、無いよりまし ぐらいのつもりで適当にでも書いておきましょう。私も英語は苦手で、なにか違う気はするなと思いつつ、多分伝わるだろうという感じで一応つけています。

メッセージファイルは YAML(YAML Ain't a Markup Language) というフォーマットでかかれます。これは読み書きしやすい XML のようなもので、 ruby ではよく使用されるフォーマットです。 ここでは YAML の詳しい説明は行わず、メッセージファイルとしての最低限の説明だけにします。より詳しく知りたい方は他のサイトを見てください。

* Ruby Magazine

** http://jp.rubyist.net/magazine/?0009-YAML

* 公式ページ

** http://www.yaml.org/

h2. YAML ファイル

config/locales/en.yml ファイルの中身をみてみましょう。

<pre><code class="yaml">

# English strings go here for Rails i18n

en:

  my_label: "My label"

</code></pre>

最初の <notextile>#</notextile> から始まる行はコメントです。

先頭は *言語の識別子:* で始める必要があります。日本語の場合は *ja:* となります。

その後、メッセージを取得するためのキーとメッセージのペアを書いていくことになります。

<pre><code class="yaml">

言語の識別子:

  シンボル名: メッセージ

  シンボル名: メッセージ

          # :

</code></pre>

記述する場合にはインデントに気をつけてください。YAML では *インデントによって階層化* されます。また、 ファイル内での *タブは使用禁止* です。

また生成されたファイルではメッセージをダブルクオートで囲んでいますが、簡単なものであれば囲う必要はありません。大抵は囲っていなくても大丈夫です。

あとこれはフォーマットの仕様ではなく Rals の決まりなのですが、文字コードは必ず *UTF-8* にしてください。

h2. メニューを日本語化する

いきなり、少し特殊な例になってしまいますが、作ったメニューと権限レポートの項目を日本語化することにします。そのためのメッセージを en.yml と ja.yml に追加します。また、生成時に付けられているコメントは削除しています。 

ja.yml の方のファイルの中身は次のような感じです。

<pre><code class="yaml">

ja:

  label_standard: 標準

  project_module_standard: 標準プラグイン

  permission_view_foos: サンプルデータの閲覧

  permission_manage_foos: サンプルデータの管理

</code></pre>

これを記述したら、 Redmine を起動してメニューと権限レポートを確認してみましょう。

ちなみにメッセージファイルも app 以下と同様に development モードでは再起動なしで編集が反映されます。

h3. メニュー

作成しているプラグインのメニューを見てください。 ja.yml に記述しただけでいきなり日本語化されています。

!sample_proj_menu_ja.png!

これはメニューの場合、 *label_メニュー項目名* というシンボル名で対応する翻訳メッセージを探し、見つかればその翻訳メッセージでラベルを表示するようになっているためです。 サンプルではメニューの項目名を starndard にしました。そこで label_standard をキーとするメッセージを書いたので、メニュー項目が日本語化されたというわけです。

h3. モジュール名、権限レポートの項目

権限レポートも見てみましょう。こちらも日本語化されています。

!permission_ja.png!

モジュール名は *project_module_モジュール名* というシンボル名のメッセージが使用されます。 init.rb の project_module メソッドでモジュール名を :standard としたので、 project_module_standard のメッセージが使用されています。

権限メニューの権限項目で使用されるメッセージのシンボルは *permission_権限名* です。

<pre><code class="ruby">

  project_module :standard do

    permission :view_foos, :foos => [:index, :show]

    permission :manage_foos, {:foos => [:new, :edit, :destroy]},

               :require => :member

  end

</code></pre>

モジュール名はプロジェクトの設定ページなどでも使用されますが、そちらも日本語で表示されるようになっていると思います。

h2. メッセージの取得方法

それではメッセージの通常の取得方法に移ります。 メッセージを取得するには i18n の次のメソッドを使用します。

|_. メソッド |_. 引数 |_. 例 |

| l | メッセージのシンボル名、Time などのオブジェクト | l(:label_standard) |

| t | メッセージキーの文字列 | t('label_standard') |

*l* メソッドの場合、メッセージだけでなく、日付などのオブジェクトを渡して地域別の表示形式にした文字列を取得することも出来ます。通常こちらを使用します。

*t* の場合はシンボル名ではなく、文字列を渡します。基本的に l を使えばいいのですが、メッセージを階層化した場合などはこちらを使用して t('foo.bar') というようにアクセスします。

また、 app 以下のファイル内では場合は l, t をそのまま記述できますが、 init.rb や lib 以下のファイル中では *I18n.l* というようにモジュール名を指定しておく必要があります。ただし、 Rails の名前の推測によるファイルのロードのおかげで i18n を require する必要はありません。

実際に index ページで使って表示してみましょう。

<pre><code class="rhtml">

<h2> <%=h l :label_standard %> </h2>

</code></pre>

ここの *h* は Rails のメソッドで <>& などの html で使用できない文字を <notextile>&amp;</notextile> といった形式に変換してます。

!i18n_index.png!

h2. サンプルプラグインのメッセージ

サンプルプラグインのメッセージファイルに今後使用しそうなメッセージも追加します。

*en.yml*

<pre><code class="yaml">

en:

  label_standard: Standard

  project_module_standard: Standard plugin

  permission_view_foos: View sample data

  permission_manage_foos: Manage sample data

  label_foos_new: New sample data

  label_foo: Sample data

</code></pre>

*ja.yml*

<pre><code class="yaml">

ja:

  label_standard: 標準

  project_module_standard: 標準プラグイン

  permission_view_foos: サンプルデータの閲覧

  permission_manage_foos: サンプルデータの管理

  label_foos_new: 新しいサンプルデータ

  label_foo: サンプルデータ

</code></pre>

ちょっと少ないと思いましたか？ 

プラグインでは Redmine でもともと定義されているメッセージも使用できます。"編集"や"説明"といったよく使うラベルは Redmine のものを使用します。このためサンプルで記述するメッセージは少なくなっています。

これはサンプルだから手を抜いているというわけではありません。メッセージを追加する場合はまず Redmine の @app/config@ 以下のメッセージファイルですでに定義ずみでないか調べ、なるべく Redmine のものを使用した方がよいと私は思います。

そうすると Redmine のバージョンが上がった場合、メッセージが翻訳されなくなる危険性がありますが、Redmine のものを利用した方がプラグインを公開した場合などで翻訳者の負担が減りますし、 DRY だと思うからです。

---

| [[プラグイン開発ガイド|^]] | [[GuideForProject|<<]] | [[GuideIndexAction|>>]] |