Localizzare le estensioni di Visual Studio

Le estensioni VisualStudio.Extensibility usano i file string-resources.json per la localizzazione. Questo approccio localizza i nomi visualizzati dei comandi, le descrizioni comando e altri metadati di estensione che supportano la localizzazione.

Come funziona la localizzazione

Le proprietà che supportano la localizzazione usano % delimitatori per fare riferimento alle chiavi delle risorse stringa. Il compilatore genera un avviso se queste proprietà sono impostate su un valore non localizzabile. Per localizzare una stringa, racchiudere la chiave di risorsa stringa con % caratteri:

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

string-resources.json

L'estensione deve fornire un string-resources.json file per ogni linguaggio supportato dall'estensione. Questo file JSON è un dizionario di coppie chiave/valore in cui la chiave è un identificatore univoco globale per una risorsa stringa e il valore è la stringa localizzata.

Impostazione predefinita (inglese) - .vsextension/string-resources.json:

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

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

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

Struttura delle directory

Distribuisci i string-resources.json file nella .vsextension directory. Inserire un file predefinito nella directory radice e i file specifici per le impostazioni locali nelle sottocartelle denominate con il codice delle impostazioni locali:

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

Il string-resources.json nella radice di .vsextension viene usato come fallback quando Visual Studio è impostato su una lingua per cui l'estensione non fornisce un file localizzato.

Localizzare le stringhe dell'interfaccia utente di runtime

L'approccio string-resources.json precedente copre i metadati dell'estensione (nomi dei comandi, descrizioni comando) che vengono caricati automaticamente da Visual Studio. Per le stringhe visualizzate in fase di esecuzione nell'interfaccia utente dell'estensione, ad esempio etichette delle finestre degli strumenti, testo della finestra di dialogo o messaggi di stato, è necessario caricare manualmente le traduzioni.

Approccio consigliato: file di risorse JSON incorporati

1. Creare file JSON specifici delle impostazioni locali nel progetto ,ad esempio 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. Contrassegnarle come risorse incorporate in .csproj:

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

3. Caricare il file corretto in fase di esecuzione in base alle impostazioni cultura correnti:

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. Usare l'helper nel codice dell'estensione:

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

Tips

✅ DO

• Mantenere le chiavi stringa univoche e descrittive a livello globale.
• Specificare sempre un file di fallback in inglese.
• Eseguire il test con un Language Pack di Visual Studio non in inglese installato.
• Usare CultureInfo.CurrentUICulture per le stringhe dell'interfaccia utente.

❌ DON'T

• Non usare chiavi generice come "Label1".
• Non presupporre che le impostazioni cultura dell'utente corrispondano sempre alle impostazioni locali specificate.
• Non codificare direttamente nel codice le stringhe visibili all’utente.
• Non usare CultureInfo.CurrentCulture per le stringhe dell'interfaccia utente; serve per la formattazione di numeri e date.

Contenuti correlati

• Pubblica la panoramica dell'estensione
• Pubblicare nel Marketplace