Visual Studio 拡張機能をローカライズする

VisualStudio.Extensibility 拡張機能では、ローカライズ用に string-resources.json ファイルを使用します。 このアプローチでは、コマンドの表示名、ヒント、およびローカライズをサポートする他の拡張機能メタデータをローカライズします。

Note

VSSDK 拡張機能で使用される .vsixlangpack 方式は、VisualStudio.Extensibility 拡張機能では サポートされていません。 string-resources.json を代わりに使用します。

ローカリゼーションの仕組み

ローカリゼーションをサポートするプロパティでは、% 区切り記号を使用して文字列リソース キーを参照します。 これらのプロパティがローカライズできない値に設定されている場合、コンパイラは警告を発します。 文字列をローカライズするには、文字列リソース キーを % で囲みます。

public override CommandConfiguration CommandConfiguration => new("%MyExtension.MyCommand.DisplayName%")
{
    TooltipText = "%MyExtension.MyCommand.TooltipText%"
};

string-resources.json

拡張機能は、サポートする各言語ごとに string-resources.json ファイルを用意する必要があります。 この JSON ファイルは、キーと値のペアのディクショナリです。キーは文字列リソースのグローバル一意識別子であり、値はローカライズされた文字列です。

既定値 (英語) — .vsextension/string-resources.json:

{
    "MyExtension.MyCommand.DisplayName": "My Command",
    "MyExtension.MyCommand.TooltipText": "Runs my command"
}

ドイツ語 — .vsextension/de/string-resources.json:

{
    "MyExtension.MyCommand.DisplayName": "Mein Befehl",
    "MyExtension.MyCommand.TooltipText": "Führt meinen Befehl aus"
}

ディレクトリの構造

.vsextension ディレクトリにある string-resources.json ファイルをデプロイします。 既定のファイルはルートに配置し、ロケール固有のファイルはロケール コードで指定されたサブフォルダーに配置します。

.vsextension/
├── string-resources.json          (default / fallback)
├── de/
│   └── string-resources.json      (German)
├── es/
│   └── string-resources.json      (Spanish)
├── fr/
│   └── string-resources.json      (French)
└── ja/
    └── string-resources.json      (Japanese)

.vsextension のルートにある string-resources.json は、Visual Studio が、拡張機能ではローカライズされたファイルが提供されていない言語に設定されている場合のフォールバックとして使用されます。

ランタイム UI 文字列をローカライズする

上記のstring-resources.jsonアプローチでは、Visual Studio が自動的に読み込む拡張メタデータ (コマンド名、ツールヒント) を対象としています。 ツール ウィンドウのラベル、ダイアログ テキスト、ステータス メッセージなど、拡張機能の UI に実行時に表示される文字列の場合は、翻訳を自分で読み込む必要があります。

  1. プロジェクトにロケール固有の JSON ファイルを作成してください (たとえば、 Strings/en.json、 Strings/de.json):
// Strings/en.json
{
    "ToolWindow.Title": "My Tool Window",
    "Status.Loading": "Loading project data...",
    "Error.NotFound": "The requested item was not found."
}
  1. ご使用の .csproj で埋め込みリソースとしてマークしてください。
<ItemGroup>
  <EmbeddedResource Include="Strings\*.json" />
</ItemGroup>
  1. 現在のカルチャに基づいて、実行時に正しいファイルを読み込みます。
using System.Globalization;
using System.Reflection;
using System.Text.Json;

public static class LocalizedStrings
{
    private static readonly Dictionary<string, string> Strings = LoadStrings();

    private static Dictionary<string, string> LoadStrings()
    {
        var culture = CultureInfo.CurrentUICulture.TwoLetterISOLanguageName;
        var assembly = Assembly.GetExecutingAssembly();

        // Try culture-specific, then fall back to English
        var resourceName = $"MyExtension.Strings.{culture}.json";
        var stream = assembly.GetManifestResourceStream(resourceName)
            ?? assembly.GetManifestResourceStream("MyExtension.Strings.en.json");

        if (stream is null) return new();

        using var reader = new StreamReader(stream);
        return JsonSerializer.Deserialize<Dictionary<string, string>>(reader.ReadToEnd()) ?? new();
    }

    public static string Get(string key) =>
        Strings.TryGetValue(key, out var value) ? value : key;
}
  1. 拡張機能コードでヘルパーを使用します。
// In a tool window, command handler, or dialog
var title = LocalizedStrings.Get("ToolWindow.Title");

Important

メタデータのローカライズ (.vsextension/ in string-resources.json) とランタイム文字列のローカライズを混在させないでください。 それぞれ用途が異なります:

  • .vsextension/string-resources.json — コマンド名とヒントのために VS ホストで読み込まれる
  • 埋め込みリソースファイル — UI 文字列用に拡張機能のコードによって読み込まれる

Tips

✅ DO

  • 文字列キーはグローバルに一意でわかりやすいものにします。
  • 常に英語のフォールバック ファイルを用意してください。
  • 英語以外の Visual Studio 言語パックをインストールした状態でテストします。
  • UI 文字列では CultureInfo.CurrentUICulture を使用します。

❌ 禁止事項

  • "Label1"などの汎用キーは使用しないでください。
  • ユーザーの文化が常に指定されたロケールと一致すると決めつけないでください。
  • ユーザー向けの文字列をコード内で直接ハードコーディングしないでください。
  • UI 文字列には CultureInfo.CurrentCulture を使用しないでください。数値と日付の書式設定用です。