Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
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.
Abordagem recomendada: ficheiros de recursos JSON incorporados
- 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."
}
- Marque-os como recursos incorporados no seu
.csproj:
<ItemGroup>
<EmbeddedResource Include="Strings\*.json" />
</ItemGroup>
- 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;
}
- 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.CurrentUICulturepara 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.CurrentCulturepara textos da interface do utilizador; destina-se à formatação de números e datas.