GNU gettext utilities: C#

15.5.12 C#

RPM: pnet、pnetlib 0.6.2以降、またはmono 0.29以降
ファイル拡張子: cs
文字列構文: "abc", @"abc"
gettextの略記: _("abc")
gettext/ngettext関数: GettextResourceManager.GetString, GettextResourceManager.GetPluralString GettextResourceManager.GetParticularString GettextResourceManager.GetParticularPluralString
textdomain: new GettextResourceManager(domain)
bindtextdomain: —
実行可能ファイルを含むディレクトリーのサブディレクトリーにコンパイルされたmessage catalogが配置されます
setlocale: 自動
必要条件: —
GNU gettextの使用またはエミュレート: —
C# specific message catalog formatを使用してください
抽出プログラム: xgettext -k_
位置の書式: String.Format "{1} {0}"
可搬性: 完全な可搬性がある
po-modeでのマーキング: —

文字列をインターナショナライズ可能とマークする前に、文字列結合演算子を使って、String.Format呼び出しで変換が必要な文字列を結合してください。たとえば"file "+filename+" not found"は、String.Format("file {0} not found", filename)となります。これを行った後のみ、文字列をマークして抽出することが可能になります。

GNU gettextは、ResourceManagerおよびResourceSetという名前の、C#/.NET本来のインターナショナリゼーションメカニズムを使います。アプリケーションはResourceManagerのメソッドを使って、母国語に翻訳された文字列を取得します。メッセージカタログファイルをインメモリーに展開したものが、ResourceSetのインスタンスです。ResourceManagerは、翻訳を検索する必要が生じると、ResourceSetのインスタンスをロード・アクセスします。

C#のランタイムが直接ロードできるResourceSetには、.resourcesファイル、および.dllファイルという、2つの形式があります:

.resourcesの形式はバイナリーのファイルで、通常はresgenまたはmonoresgenユーティリティーにより生成され、この形式はplural formをサポートしません。.resourcesは、.NETの.exeファイルに埋め込むこともできます。これは、メッセージカタログをロードするためにファイルシステムにアクセスするかどうかに影響を及ぼすだけで、メッセージカタログの内容には影響しません。
一方.dllの形式は、ソースコードの.csからコンパイルされたバイナリーファイルで、plural formをサポートします(これは以下で記述するように、GNU gettext APIを通じてアクセスすることにより提供されます)。

これら .NETの.dllや.exeファイルは、特定のプラットフォームに限定されたものではないことに注意してください。これらのファイル形式、およびC#のためのGNU gettextは、任意のプラットフォームで使用できます。

msgfmtプログラムに‘--csharp-resources’オプションを指定することにより、POファイルを.resourcesファイルに変換できます。また、msgunfmtプログラムに‘--csharp-resources’オプションを指定することにより、.resourcesファイルからPOファイルに逆変換できます。これらの処理は、resgenプログラム(pnetパッケージ)や、monoresgenプログラム(mono/mcsパッケージ)でできる場合もあります。これらのプログラムは、.resourcesファイルからPOファイルへの逆変換もできます。しかし、この文書を記述している時点(2004年1月)では、monoresgenコンバーターにはバグが多く、resgenコンバーターはPOファイルのエンコーディングを無視することに注意してください。

msgfmtプログラムに--csharpオプションを指定することにより、POファイルを.dllファイルに変換できます。GettextResourceSet(このクラスもResourceSetのサブクラスです)のサブクラスを含んだ、.dllファイルを得ることができます。また、msgunfmtプログラムに--csharpオプションを指定することにより、サブクラスGettextResourceSetを含む.dllファイルをPOファイルに逆変換できます。

.resources形式に比べて、.dll形式には、以下のような利点があります:

自由なローカライズ: アプリケーションをビルド・配布した後でも、ユーザーは自分の翻訳を自由に追加できます。一方、システムにより提供されるResourceManagerのコンストラクターをプログラマーが使った場合、アプリケーション用の一連の.resourcesファイルは、アプリケーションのビルド時に指定しなければならず、後から拡張はできません。
Plural の処理: .dll形式のメッセージカタログは、pluralを処理するための関数GetPluralStringをサポートします。一方、.resourcesファイルは、含まれているデータと、単一の文字列にもとづく検索だけをサポートします。
Context の処理: .dll形式のメッセージカタログは、contextにもとづく問い合わせをおこなうための関数GetParticularStringおよびGetParticularPluralStringをサポートします。一方、.resourcesファイルは、含まれているデータと、単一の文字列にもとづく検索だけをサポートします。
GettextResourceManagerは、.dll形式の中のメッセージカタログのロードと、メッセージ単位でのロードも提供します。たとえばAustrian(de_AT)のlocaleでは、メッセージがAustrianのメッセージカタログにないときに、German(de)のメッセージカタログが使用されます。つまり、Austrianの翻訳者は、Germanの翻訳とは異なるいくつかのメッセージだけを、Austrianに翻訳する必要があるということです。一方、.resourcesファイルでは、各メッセージカタログは、それ自身に含まれるすべてのメッセージの翻訳を提供しなければなりません。
GettextResourceManagerは、翻訳が見つからないときはEnglishのmsgidを戻すというフォールバック付きで、.dll形式のメッセージカタログをロードします。一方、.resourcesファイルでは、その.resourcesが言語中立な場合、フォールバックを明示的に提供しなければなりません。

プログラム用のAPIという面では、プログラマーは標準のResourceManager APIと、GNU GettextResourceManager API のどちらを使うこともできます。前者のResourceManagerのサブクラスが、後者のGettextResourceManagerなので、後者の方が拡張されています。

System.Resources.ResourceManager API
このAPIは、.resources形式のリソースにたいして動作します。

ResourceManagerを生成するには、以下のようにします
```
  new ResourceManager(domainname, Assembly.GetExecutingAssembly())
```
GetString関数は、文字列にたいする翻訳を戻します。翻訳がない場合はnullが戻されることに注意してください(例: これはフォールバックのリソースファイルの場合にも適用されます)。
GNU.Gettext.GettextResourceManager API
このAPIは、.dll形式のリソースにたいして動作します。

Reference documentationは、csharpdoc directoryにあります。

ResourceManagerを生成するには、以下のようにします
```
  new GettextResourceManager(domainname)
```
このAPIのGetString関数は、翻訳された文字列を戻します。翻訳がない場合には、msgidが変更されずに戻されることに注意してください。

GetPluralString関数は、Cのngettext関数のように、文字列にたいしてplural処理をした翻訳を戻します。

GetParticularString関数は、Cのpgettext関数のように、特定のcontextが指定された文字列の翻訳を戻します。翻訳がない場合には、msgidが変更されずに戻されることに注意してください。

GetParticularPluralString関数は、Cのnpgettext関数のように、特定のcontextが指定された文字列にたいして、plural処理をした翻訳を戻します。

このAPIを使うために必要なのは、GNU gettextパッケージの一部であるGNU.Gettext.dllだけで、これはLGPLのもとで配布されています。

2つのアプローチをミックスすることもできます: たとえばGNU.Gettext.GettextResourceManagerコンストラクターは使うが、ResourceManager型とGetStringメソッドだけを使うような場合です。これはPOファイル用のツールに適合させたいが、ResourceManagerを使う既存のソースコードを変更したくなくて、(まだ)GetPluralStringメソッドが必要ないときには適しているでしょう。

2番目のAPIを使うためには、examplesディレクトリーのhello-csharp、hello-csharp-formsの2つの例が利用できます。

ではAPIの使い方と、‘GetString’の略記をしてみましょう。以下の3つの用法から選択することができましょう:

あなたのプロジェクトに‘Util’という一意なクラスがあるとき、ResourceManagerのインスタンスを保持するstaticな変数を定義する場合は、以下のような略記を定義します:
```
public static GettextResourceManager MyResourceManager =
  new GettextResourceManager("domain-name");
```
そして、インターナショナライズする文字列を含むすべてのクラスに、以下の宣言を含めます
```
private static GettextResourceManager Res = Util.MyResourceManager;
private static String _(String s) { return Res.GetString(s); }
```
これで以下のようにして略記を使うことができます:
```
Console.WriteLine(_("Operation completed."));
```

resource managerの定義だけを含む、とても短い名前の‘S’というクラスを追加して、以下のような略記を定義します:

public class S {
  public static GettextResourceManager MyResourceManager =
    new GettextResourceManager("domain-name");
  public static String _(String s) {
     return MyResourceManager.GetString(s);
  }
}

これで以下のようにして略記を使うことができます:

Console.WriteLine(S._("Operation completed."));

2つの用法のどちらを選ぶかは、すべてのクラスに上記の2行をコピーするのがよいか、それともすべてのクラスに1文字のクラスを追加するのがよいかによります。