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 に実行時に表示される文字列の場合は、翻訳を自分で読み込む必要があります。
推奨される方法: 埋め込み JSON リソース ファイル
- プロジェクトにロケール固有の 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."
}
- ご使用の
.csprojで埋め込みリソースとしてマークしてください。
<ItemGroup>
<EmbeddedResource Include="Strings\*.json" />
</ItemGroup>
- 現在のカルチャに基づいて、実行時に正しいファイルを読み込みます。
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;
}
- 拡張機能コードでヘルパーを使用します。
// 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を使用しないでください。数値と日付の書式設定用です。