Traduzir e adaptar extensões do Visual Studio

As extensões VisualStudio.Extensibility usam string-resources.json ficheiros para localização. Esta abordagem localiza nomes de exibição de comandos, dicas de ferramentas e outros metadados de extensão que suportam a localização.

Note

O .vsixlangpack mecanismo utilizado pelas extensões VSSDK não é suportado pelas extensões VisualStudio.Extensibility. Utilize string-resources.json em substituição.

Como funciona a localização

Propriedades que suportam a localização utilizam delimitadores % para referenciar chaves de recursos de cadeia de caracteres. O compilador emite um aviso se estas propriedades forem definidas para um valor não localizável. Para localizar uma cadeia, rodeie a chave de recursos da cadeia com % caracteres:

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

string-resources.json

A sua extensão deve fornecer um string-resources.json ficheiro para cada língua suportada. Este ficheiro JSON é um dicionário de pares chave/valor onde a chave é um identificador globalmente único para um recurso de cadeia e o valor é a cadeia localizada.

Predefinição (Inglês) — .vsextension/string-resources.json:

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

Alemão — .vsextension/de/string-resources.json:

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

Estrutura do diretório

Coloca os string-resources.json ficheiros no .vsextension diretório. Coloque um ficheiro predefinido na raiz e ficheiros específicos da região em subpastas nomeadas por código da região:

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

O string-resources.json na raiz de .vsextension é usado como predefinição quando o Visual Studio está definido para um idioma para o qual a sua extensão não fornece um ficheiro localizado.

Localizar textos da interface em tempo de execução

A abordagem string-resources.json acima abrange os metadados das extensões (nomes de comandos, descrições) que o Visual Studio carrega automaticamente. Para strings exibidas em tempo de execução na interface da sua extensão — como etiquetas das janelas de ferramentas, texto de diálogo ou mensagens de estado — precisa de carregar as traduções.

  1. Crie ficheiros JSON específicos da locale no seu projeto (por exemplo, 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. Marque-os como recursos incorporados no seu .csproj:
<ItemGroup>
  <EmbeddedResource Include="Strings\*.json" />
</ItemGroup>
  1. Carregue o ficheiro correto em tempo de execução com base na cultura atual:
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. Utilize a função auxiliar no código da sua extensão:
// In a tool window, command handler, or dialog
var title = LocalizedStrings.Get("ToolWindow.Title");

Important

Não misture a localização de metadados (string-resources.json em .vsextension/) com a localização de cadeias em tempo de execução. Servem propósitos diferentes:

  • .vsextension/string-resources.json — carregado pelo anfitrião VS para nomes de comandos e dicas de ferramentas
  • Ficheiros de recursos embutidos — carregados pelo seu código de extensão para cadeias de UI

Tips

✅ DO

  • Mantenha as chaves de cadeia globalmente únicas e descritivas.
  • Fornecer sempre um ficheiro alternativo em inglês.
  • Teste com um pacote de idiomas do Visual Studio que não seja em inglês instalado.
  • Usa CultureInfo.CurrentUICulture para cadeias da IU.

❌ NÃO

  • Não uses chaves genéricas como "Label1".
  • Não assumas que a cultura do utilizador coincidirá sempre com uma configuração regional fornecida.
  • Não codifique diretamente os textos apresentados ao utilizador no código.
  • Não utilize CultureInfo.CurrentCulture para textos da interface do utilizador; destina-se à formatação de números e datas.