SummitUI - Localization

Overview

SummitUI components use localized strings for ARIA labels, screen reader announcements, and other accessibility-related text. The library ships with English defaults and provides multiple ways to customize these strings for your application's locale.

Note: Localization in SummitUI focuses on accessibility strings (ARIA labels, screen reader text), not visible UI text. User-facing content like button labels should be provided by your application.

Resource Keys

SummitUI uses the following resource keys for accessibility strings:

Key	Default Value	Description
`Dialog_CloseLabel`	Close dialog	ARIA label for dialog close buttons
`Popover_CloseLabel`	Close	ARIA label for popover close buttons
`Combobox_ClearAllLabel`	Clear all selections	ARIA label for combobox clear button
`Calendar_NextMonthLabel`	Next month	ARIA label for calendar next month button
`Calendar_PreviousMonthLabel`	Previous month	ARIA label for calendar previous month button
`Calendar_GridInstructions`	Use arrow keys to navigate dates, Enter or Space to select	Screen reader instructions for calendar grid
`Calendar_DateSelectedAnnouncement`	{0} selected	Screen reader announcement when date is selected
`DateField_YearLabel`	Year	ARIA label for year segment
`DateField_MonthLabel`	Month	ARIA label for month segment
`DateField_DayLabel`	Day	ARIA label for day segment
`DateField_HourLabel`	Hour	ARIA label for hour segment
`DateField_MinuteLabel`	Minute	ARIA label for minute segment
`DateField_DayPeriodLabel`	AM/PM	ARIA label for AM/PM segment

Option 1: Custom Localizer

For full control, implement the ISummitUILocalizer interface and register it in your DI container. This is useful when you want to use your own localization system or need dynamic translations.

1. Create your localizer class

csharp

using SummitUI;

public class SwedishSummitUILocalizer : ISummitUILocalizer
{
    private readonly Dictionary<string, string> _translations = new()
    {
        ["Dialog_CloseLabel"] = "Stäng dialogrutan",
        ["Popover_CloseLabel"] = "Stäng",
        ["Combobox_ClearAllLabel"] = "Rensa alla val",
        ["Calendar_NextMonthLabel"] = "Nästa månad",
        ["Calendar_PreviousMonthLabel"] = "Föregaende månad",
        ["Calendar_GridInstructions"] = "Använd piltangenterna för att navigera, Enter eller Mellanslag för att välja",
        ["Calendar_DateSelectedAnnouncement"] = "{0} valt",
        ["DateField_YearLabel"] = "År",
        ["DateField_MonthLabel"] = "Månad",
        ["DateField_DayLabel"] = "Dag",
        ["DateField_HourLabel"] = "Timme",
        ["DateField_MinuteLabel"] = "Minut",
        ["DateField_DayPeriodLabel"] = "FM/EM",
    };

    public string this[string key] =>
        _translations.TryGetValue(key, out var value) ? value : key;

    public string this[string key, params object[] arguments] =>
        string.Format(this[key], arguments);
}

2. Register in Program.cs

csharp

// Program.cs
builder.Services.AddSummitUI();

// Override with your custom localizer
builder.Services.AddSingleton<ISummitUILocalizer, SwedishSummitUILocalizer>();

Important: Register your custom localizer after calling AddSummitUI() to override the default implementation.

Option 2: Resource Files (.resx)

The default localizer uses .NET's IStringLocalizer<T> which supports satellite assemblies. You can provide translations by creating resource files in your application.

1. Enable localization services

csharp

// Program.cs
builder.Services.AddLocalization(options =>
    options.ResourcesPath = "Resources");

builder.Services.AddSummitUI();

2. Create resource files

Create SummitUIResources.{culture}.resx files in a Resources folder. For example, for French translations:

xml

<!-- Resources/SummitUIResources.sv.resx -->
<?xml version="1.0" encoding="utf-8"?>
<root>
  <data name="Dialog_CloseLabel" xml:space="preserve">
    <value>Stäng dialogrutan</value>
  </data>
  <data name="Calendar_NextMonthLabel" xml:space="preserve">
    <value>Nästa månad</value>
  </data>
  <data name="Calendar_PreviousMonthLabel" xml:space="preserve">
    <value>Föregående månad</value>
  </data>
  <!-- Add other translations... -->
</root>

3. Configure your project

Update your .csproj to embed the resources:

xml

<ItemGroup>
  <EmbeddedResource Update="Resources\SummitUIResources.*.resx">
    <Generator>ResXFileCodeGenerator</Generator>
  </EmbeddedResource>
</ItemGroup>

User-Facing Text

Some components require user-facing text that should be localized by your application, not the library. These are exposed as required parameters rather than using the internal localizer.

AlertDialog Example

The AlertDialogOptions requires you to provide button text:

csharp

// Button text must be provided by your application
var result = await AlertDialogService.ConfirmAsync(
    "Are you sure you want to delete this item?",
    new AlertDialogOptions
    {
        Title = "Delete Item",
        ConfirmText = "Delete",    // Required - localize in your app
        CancelText = "Cancel",     // Required - localize in your app
        IsDestructive = true
    });

Why required? Button text like "Confirm" and "Cancel" is visible to users and should match your application's terminology and language. By making these required, we ensure you consciously choose appropriate text for your context.

Architecture

SummitUI's localization is built on standard .NET patterns:

ISummitUILocalizer

Interface that components use to retrieve localized strings. Can be replaced with custom implementations.

SummitUILocalizer

Default implementation using IStringLocalizer<T> with embedded .resx resources containing English defaults.

Culture Fallback

Uses .NET's standard culture fallback chain (e.g., fr-CA → fr → default).

Singleton Registration

Registered with TryAddSingleton, allowing you to override with your own implementation.