SmartCoreHub.Localization.SDK 20260727.438.0

SmartCoreHub.Localization.SDK

SDK para consumo da SmartCoreHub.Localization.API com autenticacao por API Key.

Pacote auto-isolado: nao depende de SmartCoreHub.Core.SDK. Cliente NuGet recebe apenas Localization.SDK (+ Microsoft.Extensions). Detalhes: Isolamento-Core.md.

Extensao VS Code / Cursor: SmartCoreHub Localization SDK VC — Configure Connection, playground, snippets schl-* e contexto para agentes (IdeExtensions).

Novidades da implementacao de cache

• Cache opcional para GetCurrentLanguageAsync e GetByLanguageAsync
• Quando Cache.Enabled = true, a primeira consulta usa ListResourcesAsync e armazena o resultado
• Chamadas seguintes retornam do cache
• Suporte a provider customizado via ILightweightCacheProvider (neste pacote)
• Operacoes de manutencao: InvalidateCacheAsync(key) e ClearCacheAsync()

Locale padrao (sem expor headers HTTP)

• Configure DefaultLocale (ex.: "pt-BR") ou use DefaultRequestSettings com LocalizationSdkRequestOption.Locale.
• O SDK mapeia internamente para o header HTTP correto (Accept-Language).
• Se nenhum locale for informado, o SDK envia automaticamente a cultura atual da thread (CultureInfo.CurrentUICulture).

Requisitos

• Um dos targets suportados pelo pacote NuGet:
  • netstandard2.0 / netstandard2.1
  • net6.0
  • net8.0
  • net10.0
• Endpoint da Localization API
• API Key valida

Instalacao

dotnet add package SmartCoreHub.Localization.SDK

Configuracao (DI)

using SmartCoreHub.Localization.SDK.Extensions;

builder.Services.AddLocalizationSdk(options =>
{
    options.BaseUrl = "https://api.smartcorehub.com";
    options.ApiKey = "SUA_API_KEY";
    options.Timeout = TimeSpan.FromSeconds(30);
    options.DefaultLocale = "pt-BR";
    options.Cache = new CacheOptions
    {
        Enabled = true,
        Ttl = TimeSpan.FromMinutes(10)
    };
});

Com DefaultRequestSettings (array tipado):

using SmartCoreHub.Localization.SDK.Configuration;

builder.Services.AddLocalizationSdk(options =>
{
    options.BaseUrl = "https://api.smartcorehub.com";
    options.ApiKey = "SUA_API_KEY";
    options.DefaultRequestSettings =
    [
        LocalizationSdkRequestSetting.Locale("pt-BR")
    ];
});

Com provider customizado:

using SmartCoreHub.Localization.SDK.Caching;
using SmartCoreHub.Localization.SDK.Extensions;

builder.Services.AddLocalizationSdk(options =>
{
    options.BaseUrl = "https://api.smartcorehub.com";
    options.ApiKey = "SUA_API_KEY";
    options.Cache = new CacheOptions
    {
        Enabled = true,
        Provider = new LightweightMemoryCacheProvider(),
        Ttl = TimeSpan.FromMinutes(10)
    };
});

Breaking changes

Isolamento do Core.SDK (atual)

Quem passou a tipar DI/opcoes com tipos SmartCoreHub.Core.SDK.* apos o Lote 7 deve migrar de volta aos tipos deste pacote:

Nao ha dependencia NuGet de SmartCoreHub.Core.SDK.

Historico Lote 7 (supersedido pelo isolamento)

O Lote 7 havia removido shims locais e apontado para Core; o isolamento reintroduz os contratos owned no Localization (sem cascas Obsolete).

Uso com ILocalizationApiClient

using SmartCoreHub.Localization.SDK.Abstractions;

public sealed class MyService
{
    private readonly ILocalizationApiClient _client;

    public MyService(ILocalizationApiClient client)
    {
        _client = client;
    }

    public async Task<string?> GetCurrentAsync(CancellationToken ct)
    {
        return await _client.GetCurrentLanguageAsync("accessdenied.goDashboard", ct);
    }

    public async Task<string?> GetByLanguageAsync(CancellationToken ct)
    {
        return await _client.GetByLanguageAsync("accessdenied.goDashboard", "pt-BR", ct);
    }

    public async Task<int> CountResourcesAsync(CancellationToken ct)
    {
        var resources = await _client.ListResourcesAsync(ct);
        return resources.Length;
    }

    public async Task RefreshLocalizationCacheAsync(CancellationToken ct)
    {
        await _client.ClearCacheAsync(ct);
    }
}

Uso sem DI (Console/Desktop)

using SmartCoreHub.Localization.SDK.Clients;
using SmartCoreHub.Localization.SDK.Configuration;

var client = new LocalizationApiClient(new LocalizationSdkOptions
{
    BaseUrl = "https://api.smartcorehub.com",
    ApiKey = "SUA_API_KEY",
    Timeout = TimeSpan.FromSeconds(30),
    DefaultLocale = "pt-BR"
});

var value = await client.GetCurrentLanguageAsync("accessdenied.goDashboard");
Console.WriteLine(value);

API principal

• GetCurrentLanguageAsync(resourceKey)
• GetByLanguageAsync(resourceKey, languageKey)
• ListResourcesAsync()
• InvalidateCacheAsync(key)
• ClearCacheAsync()

ListResourcesAsync retorna LocalizationResourceDto[].

Excecoes

• LocalizationConfigurationException
• LocalizationAuthenticationException
• LocalizationRequestException
• LocalizationSerializationException
• LocalizationUnauthorizedException
• LocalizationClientException
• LocalizationServerException

Documentacao interativa da API (OpenAPI)

O SDK consome a SmartCoreHub.Localization.API via HTTP. Em desenvolvimento local, a API expoe o mesmo pipeline de documentacao que as demais APIs SmartCoreHub (ver Documentation/Features/FEITOS/API-DOCUMENTATION-UI.md).

Substitua {base} pela URL HTTPS da API em execucao:

UIs e documento OpenAPI

Exemplo (Localization API em dev):

• https://localhost:61115/swagger/index.html
• https://localhost:61115/openapi/v1.json
• https://localhost:61115/scalar/v1
• https://localhost:61115/redoc
• https://localhost:61115/rapidoc

Guia completo: API-DOCUMENTATION-UI.md.

Endpoints REST (sem SDK)

Autenticacao: header X-Auth-Token com sua API key.

Documentacao publica na landing: rota /docs-api.

Observacoes

• Timeout padrao: 30 segundos.
• O header de autenticacao enviado e X-Auth-Token (gerenciado pelo SDK).
• Locale contextual e enviado internamente via Accept-Language quando DefaultLocale ou DefaultRequestSettings estao configurados.
• O cache e opcional e controlado por Cache.Enabled.

https://www.nuget.org/packages/SmartCoreHub.Localization.SDK/

Licensing / Licenciamento

English

This project is provided for non-commercial use. Commercial use requires prior authorization from SmartCoreHub through a valid commercial license purchase or an active service contract. See the LICENSE file in this project for full terms.

Portugues (PT-BR)

Este projeto e fornecido para uso nao comercial. O uso comercial exige autorizacao previa da SmartCoreHub, por meio de aquisicao de licenca comercial valida ou contrato de servico ativo. Consulte o arquivo LICENSE deste projeto para os termos completos.