作成したDLLを配布するためNuGetパッケージを作成したのだが、その時のXMLドキュメントコメントファイルの多言語化と、それをNuGetパッケージ内に納めるための方法について。
初めに
/// <summary>
/// Connect IQ関連のファイルを取り扱うためのクラス
/// </summary>
public class GarminSDKこんな形に書いておくと、このクラスを利用するときにここに記述されたコメントが表示されるドキュメントコメント。
単一言語であれば、プロジェクトのXMLドキュメントファイルを指定すればすぐに実現できる。
複数言語、例えば、英語、日本語とかを作成する場合には、ちょっと面倒な手順が必要だった。
一応、ググってみたところ以下のサイトがヒットしたので、まずはこの通りにやってみたところVisual Studio 2019のせいか、もしくは私のプロジェクトの環境だけなのか、正しく動作しなかった。
そのままでは動作しなかったのは、以下の3点。
- Visual Studioのプロジェクトから起動される「パック」もしくは「発行」に対応していなかった。
これが1番のネックかもしれない。 - nuget pack
で、パッケージを作成した場合、「Authors is required.」とエラーが出て作成できなかった。
これは、nuget specで作成した時にnuspecファイルの「<authors>$author$</authors>」の部分が間違いで、「<authors>$authors$</authors>」が正しいものだった。 - ファイルの配置内容がnuget packとVisual Studioの発行で異なる。
nugetでパックすると、dllの配置先がnet5.0となる。
Visual Studioでパックするとnet5.0-windows7.0という配置先になる。
3番目の件は、以下の場所にちょっと詳細が記述されている。
対応方法
結果、以下のような方針で対応することにした。
- ドキュメントコメントファイルは、自動生成したものをそのままでは使用しない。
- Visual Studio 2019のパック・発行でパッケージングする。
ドキュメントコメントファイル
「ドキュメントコメントファイルは、自動生成したものをそのままでは使用しない。」とはどういうことか。
C#内のドキュメントコメントは、（#if等を使えば可能だけど）複数言語を書けるようにはなっていない。
そのため日本語、英語等複数言語を用意する場合には、まずC#ソース中から生成されたxmlファイルを各言語のため翻訳をしないといけなくなる。
初めての翻訳時は、自動生成されたXMLファイルの中身をすべて翻訳すればいいのだが、その後の修正時に手間がかかることが予想される。
修正箇所が1、2か所と少ないなら問題ないが、複数個所、さらにいろいろな場所に散らばっている場合だと、翻訳先の変更箇所の特定が面倒になり、修正漏れ等が発生する可能性が出てくる。その可能性を低くするための処置になる。
実際の手順は以下の様になる。
初回手順
- 初期のXMLファイルは、自動生成で作成する。
プロジェクトのXMLドキュメントファイルにチェックを入れ、ビルドする。 - 言語ごとにフォルダを作成し、そこに自動生成したファイルコピーする。
これは、ja(日本語)、en(英語)用として用意し、プロジェクトフォルダ直下に作成されたxmlファイルをコピーしたもの。 - 言語フォルダにコピーしたものを翻訳する。
- XMLファイルの自動生成のチェックを外す。
変更時手順
- XMLファイルの自動生成にチェックを入れる。
- 生成されたXMLファイルと、そのXMLファイルと同等の言語のXMLファイルで差分を取る。
私の環境では日本語がC#内の言語なので、プロジェクトフォルダ直下のXMLファイルとjaフォルダのXMLファイルを比較する。
今回は、簡単な変更なのだが、WinMergeで差分を取ってみた。 - 上記の差分をもとに、各言語の修正箇所を洗い出し、変更していく。
vcprojの記述方法
Visual Studio 2019のパック・発行でパッケージングするため、以下のような設定をvcprojファイルに施す。
<ItemGroup>
<None Include="en\AutomationConnectIQ.Utility.xml">
<Pack>true</Pack>
<PackagePath>lib\$(TargetFramework)$(TargetPlatformVersion)</PackagePath>
</None>
<None Update="ja\AutomationConnectIQ.Utility.xml">
<Pack>true</Pack>
<PackagePath>lib\$(TargetFramework)$(TargetPlatformVersion)</PackagePath>
</None>
</ItemGroup>AutomationConnectIQ.Utility.xmlがパッキング対象のXMLドキュメントコメントファイルになる。
上側が英語用、下側が日本語用で、Pack属性とPackagePath属性で、パック対象であることと格納場所の指定を行うことになっている。
XMLドキュメントコメントファイルはdllと同じ場所もしくはその下の言語フォルダの下に格納する必要があるため、その指定をPackagePathでしている。
ここで重要なのが$(TargetFramework)$(TargetPlatformVersion)という記述。
一応これで「Target Framework Names in .NET 5」に記載されているフォルダ位置に保存されることが分かった。
また上のファイルの記述で、英語版はIncludeで、日本語版はUpdateになっている。
IncludeとUpdateの違いは、ディレクトリ名が保存先の指定に含まれているかどうか、という認識をしている。
（本当はちょっと違うのかもしれないが、IncludeとUpdateのドキュメントを見ても、よくわからなかったため、この動作による理解にとどめている）
コメント