Lokalizowanie rozszerzeń programu Visual Studio

Rozszerzenia VisualStudio.Extensibility używają plików string-resources.json na potrzeby lokalizacji. To podejście lokalizuje wyświetlane nazwy poleceń, podpowiedzi i inne metadane rozszerzenia, które można lokalizować.

Jak działa lokalizacja

Właściwości obsługujące lokalizację używają separatorów % do odwoływania się do kluczy zasobów ciągów. Kompilator generuje ostrzeżenie, jeśli te właściwości są ustawione na wartość, której nie można lokalizować. Aby zlokalizować ciąg znaków, otocz klucz zasobu ciągu znaków znakami %:

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

string-resources.json

To rozszerzenie powinno zawierać plik string-resources.json dla każdego języka obsługiwanego przez to rozszerzenie. Ten plik JSON jest słownikiem par klucz/wartość, w którym kluczem jest globalnie unikatowy identyfikator zasobu tekstowego, a wartością jest zlokalizowany tekst.

Ustawienie domyślne (angielski) — .vsextension/string-resources.json:

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

Niemiecki — .vsextension/de/string-resources.json:

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

Struktura katalogu

Wdróż string-resources.json pliki z katalogu .vsextension. Umieść plik domyślny w plikach głównych i specyficznych dla ustawień regionalnych w podfolderach o nazwie według kodu ustawień regionalnych:

.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)

Plik string-resources.json w katalogu głównym folderu .vsextension jest używany jako domyślny, gdy Visual Studio jest ustawione na język, dla którego rozszerzenie nie udostępnia zlokalizowanego pliku.

Lokalizowanie ciągów interfejsu użytkownika środowiska uruchomieniowego

Powyższe string-resources.json podejście obejmuje metadane rozszerzeń (nazwy poleceń, etykietki narzędzi), które Visual Studio ładowane automatycznie. W przypadku ciągów wyświetlanych w czasie wykonywania w interfejsie użytkownika rozszerzenia — takich jak etykiety okien narzędzi, tekst okna dialogowego lub komunikaty o stanie — należy samodzielnie załadować tłumaczenia.

Zalecane podejście: osadzone pliki zasobów JSON

1. Utwórz w projekcie pliki JSON dla poszczególnych ustawień regionalnych (na przykład 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."
}

2. Oznacz je jako zasoby osadzone w .csproj:

<ItemGroup>
  <EmbeddedResource Include="Strings\*.json" />
</ItemGroup>

3. Załaduj prawidłowy plik podczas uruchamiania na podstawie bieżącej kultury:

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;
}

4. Użyj helpera w kodzie rozszerzenia:

// In a tool window, command handler, or dialog
var title = LocalizedStrings.Get("ToolWindow.Title");

Porady

✅ DO

• Zachowaj globalnie unikalne i opisowe klucze tekstowe.
• Zawsze podaj angielski plik zapasowy.
• Przetestuj z zainstalowanym pakietem językowym Visual Studio innym niż angielski.
• Użyj CultureInfo.CurrentUICulture do ciągów interfejsu użytkownika.

❌ NIE

• Nie używaj kluczy ogólnych, takich jak "Label1".
• Nie zakładaj, że kultura użytkownika będzie zawsze zgodna z podanymi ustawieniami regionalnymi.
• Nie hardkoduj ciągów skierowanych bezpośrednio do użytkownika w kodzie.
• Nie używaj CultureInfo.CurrentCulture do ciągów interfejsu użytkownika; służy do formatowania liczb i dat.

Treści powiązane

• Opublikuj omówienie rozszerzenia
• Publikuj w Marketplace