.NETライブラリのヘルプファイル作成+他言語ローカライズ

.NETライブラリのヘルプファイルを作成ツールとそのローカライズ方法です。ヘルプファイル作成までは他のサイトで色々紹介されていますのでさらっといきます。

1.ヘルプファイルの作成

本体であるSandCastleとそれをGUIから簡単に使えるようにしてくれるSandCastleHelpFileBuilderの2つをインストールします。インストールは例によってNext連打でOkです。

sandcastle

shfb

使っていきます。ヘルプファイル作成対象のソースにXml形式でヘルプを書きます。多言語ローカライズ(今回は日、英だけ)ではxml:lang属性を付けて各国語のヘルプを用意しておきます。リンクの貼り方も下記参考にしてください。

Class1.cs

namespace TestClassLibrary
{
    using System;

    /// <summary>Class1のサマリーです</summary>
    /// <summary xml:lang="en">This is summary of Class1</summary>
    public class Class1
    {
        /// <summary>関数Hogeのサマリーです</summary>
        /// <summary xml:lang="en">This is summary of Function Hoge</summary>
        /// <param name="parameter">出力対象の文字列です</param>
        /// <param name="parameter" xml:lang="en">The Output target string</param>
        /// <exception cref="System.ArgumentException">空の文字列の場合スローされます</exception>
        /// <exception cref="System.ArgumentException" xml:lang="en">Thrown when parameter is empty string</exception>
        public void Hoge(string parameter)
        {
            if (parameter.Equals(string.Empty))
            {
                throw new ArgumentException();
            }
            Console.WriteLine(parameter);
        }
    }
}

これをXmlファイル出力の設定を付けてビルドします。

savexml

これでヘルプファイル作成対象のDLLとXmlファイルができているはず。SandCastle Help File BuilderのGUIを立ち上げ、新規にプロジェクト作成して右ペーンのDocumentation SourcesにDLLとXmlを追加します。これでビルドすれば基本的にはchm形式のヘルプファイルが出力されます。

 

2. ローカライズ

今回はヘルプファイルのローカライズが目的です。先ほど作成したXmlファイルは多言語文言が混じったものになっていますので、これらを言語ごとに分割します。もちろんC#で。

 XmlHelpFileLocalize.cs

namespace LocalizeXml
{
    using System;
    using System.Linq;
    using System.Xml.Linq;

    internal class XmlHelpFileLocalize
    {
        // "xml:lang"の ':' がXNameとして認められない.
        // 代わりに"{http://www.w3.org/XML/1998/namespace}lang"で検索
        private const string targetAttr = "{http://www.w3.org/XML/1998/namespace}lang";

        internal static void LocalizeDefault(string srcXmlFilePath, string dstXmlFilePath)
        {
            var xml = XElement.Load(srcXmlFilePath);
            RemoveAttatchedLangAttribute(xml);
            xml.Save(dstXmlFilePath);
        }

        internal static void LocalizeForeignLanguage(string srcXmlFilePath, string dstXmlFilePath, string lang)
        {
            var xml = XElement.Load(srcXmlFilePath);
            LeftAttatchedLangAttribute(xml, lang);
            xml.Save(dstXmlFilePath);
        }

        private static void RemoveAttatchedLangAttribute(XElement parent)
        {
            parent.Elements()
                .Where(i => i.Attributes()
                    .Where(a => a.Name == targetAttr).Count() != 0
                ).Remove();
            foreach (var element in parent.Elements())
            {
                RemoveAttatchedLangAttribute(element);
            }
        }

        private static void LeftAttatchedLangAttribute(XElement parent, string lang)
        {
            Func<XAttribute, bool> IsLeftTarget = a => a.Name == targetAttr && a.Value == lang;

            // 保存する属性を保有する要素の名前のシーケンスを取得
            var leftElementNames = parent.Elements()
                .Where(i => i.Attributes().Where(IsLeftTarget).Count() != 0)
                .Select(i => i.Name)
                .Distinct();

            // 上記シーケンスと同一名の要素だが、対象属性がないものを削除
            parent.Elements()
                .Where(i => leftElementNames.Contains(i.Name) && i.Attributes().Where(IsLeftTarget).Count() == 0)
                .Remove();

            foreach (var element in parent.Elements())
            {
                LeftAttatchedLangAttribute(element, lang);
            }
        }
    }
}

Consoleアプリとして上のコードを走らせるようにしておけば楽ちんですね。上のコードではxml:lang属性に基づいてファイルを分割します。まずxml:lang属性ですが、DOMならそのままアクセスできますがLinqToXmlだとXAttribute(正確にはXName)として ‘:’ がダメといわれるので、W3Cの名前空間を指定しています。

処理内容は、デフォルトの言語の場合”xml:lang”属性が付いている要素は削除します。他言語の場合指定した属性値をもつ要素だけを保持し、同一要素名の属性なし要素や別属性値がついた要素を削除しています。

できたXmlファイルをデフォルトのXmlファイルの代わりに登録して、[Project Properties]のHelp file languageに対象の言語を指定して、[Documentation] – [Build Project]を実行すれば対象のヘルプファイルが作成できます。

runimage

広告