Skip to content

Localization & RTL

Every label and announcement of the palette - the ones only screen readers hear included - is a property of BaletteStrings, and every rule of its stylesheet uses logical properties, so a palette in German or in Persian, right to left, is a matter of handing it other strings and setting dir. The palette below switches language as you click.

One palette, three languages

Its footer hints, placeholder, empty state, confirmation, disabled reason, the back button, the switch's spoken On and Off, and the word between the keys of G S all come from BaletteStrings. Type xyz for the empty state, open the export page, or arm the destructive row. The titles are translated too, with the English title as a keyword: type settings or dark in any of the three.

Delete all files
Open settings G then S
Dark mode Off
Export…

The ids are the same in every language (l10n:settings, l10n:export…), so the active row and a page that is open survive a switch - and recents and pins would too.

Handing the palette its strings

Set options.Strings for every palette, or the palette's Strings parameter for one - the palette above uses the parameter. BaletteShortcutHint takes a Strings parameter as well, for the word between the chords of a sequence.

// Every palette.
builder.Services.AddBitBaletteServices(options =>
{
    options.Strings = new BaletteStrings
    {
        Placeholder = "Befehl eingeben oder suchen…",
        NoResults = "Keine Ergebnisse für „{0}“",
        ResultsAnnouncement = "{0} Ergebnisse verfügbar",
        On = "Ein",
        Off = "Aus",
        ShortcutThen = "dann",
    };
});
@* One palette. *@
<Balette Strings="_german" />

Every property is virtual, so a subclass can read them from an IStringLocalizer - the usual resource files - instead:

public sealed class LocalizedBaletteStrings(IStringLocalizer<LocalizedBaletteStrings> localizer) : BaletteStrings
{
    public override string Placeholder => localizer[nameof(Placeholder)];
    public override string NoResults => localizer[nameof(NoResults)];
    public override string ResultsAnnouncement => localizer[nameof(ResultsAnnouncement)];
    // ...
}
@inject IStringLocalizer<LocalizedBaletteStrings> Localizer

<Balette Strings="new LocalizedBaletteStrings(Localizer)" />

Counts and plural forms

The result count is announced after every search. By default ResultsAnnouncementFor(count) picks NoResultsAnnouncement, OneResultAnnouncement or ResultsAnnouncement; a language whose plural forms one template per count cannot express overrides it. Polish has three:

public sealed class PolishStrings : BaletteStrings
{
    public override string ResultsAnnouncementFor(int count) => count switch
    {
        0 => "Brak wyników",
        1 => "1 wynik",
        _ when count % 10 is >= 2 and <= 4 && count % 100 is < 12 or > 14 => $"{count} wyniki",
        _ => $"{count} wyników",
    };
}

The Persian strings above override it too, to announce the count in Persian digits (۱۲) - a screen reader reading Persian expects them.

Translated commands

When titles are translated, add the untranslated title as a keyword - .Keywords("Open settings") on Einstellungen öffnen - so people who learned the English name still find it, as VS Code does with its English aliases. Give translated commands explicit ids, too: an id derived from the title would change with the language, and recents, pins and the active row with it.

BaletteCmd.New("Einstellungen öffnen")
    .Id("l10n:settings")         // the same in every language
    .Keywords("Open settings")   // the English name still finds it
    .Group("Allgemein")
    .Shortcut("G S", global: false)

Right to left

  • Every rule uses logical properties, so dir="rtl" on the palette or anything around it lays it out from the right: the footer's last hint, the detail pane's border and the switch's knob all follow, and arrows and chevrons are mirrored.
  • User text - titles, subtitles, badges, values, breadcrumbs, headings - isolates its own direction (dir="auto"), so an English title in a Persian UI keeps its punctuation where it belongs. Shortcut key caps always read left to right, as on the keys.
  • ← and → trade places: → points back to the start of the line, so in right-to-left text it goes back a page, and ← on an empty box opens the action panel.
  • Search folds the Arabic and Persian forms of a letter and Persian digits (see Search & ranking), and a shortcut such as G S works when a Persian layout types ل س (see Keyboard).

The palette at the top of this page turns around with the language it is handed:

<div dir="@(_language.Rtl ? "rtl" : "ltr")" lang="@_language.Code">
    <Balette Inline="true"
             IncludeRegisteredCommands="false"
             Strings="_language.Strings"
             Commands="_commands" />
</div>

@code {
    // A new list on every switch: the palette re-reads Commands when it is handed a new collection.
    private void SetLanguage(Language language)
    {
        _language = language;
        _commands = BuildCommands();
    }
}

This site's own palette goes right to left with the page: pick Language › فارسی or العربية in it, and the whole site turns around - the palette included.

This site's language is English.

Every string

Every property of BaletteStrings, with the library's English and, beside it, the language picked above. {0} and {1} are filled in with string.Format in the current culture.

PropertyWhereEnglish
Placeholder The search box Type a command or search…
PromptPlaceholder The box on a prompt without a placeholder Type a value and press Enter…
NoResults The empty state, with the query No results for “{0}”
NoResultsHint Under it Try a different search, or check for typos.
Empty A page with nothing to list Nothing to show yet.
Loading A lazy page while it loads Searching…
Recent The recents' heading Recent
Pinned The pins' heading, and a pinned row (spoken) Pinned
Suggestions The heading of ungrouped commands under the pinned and recent ones Suggestions
Modes The mode hints' heading Modes
Actions The action panel's placeholder Actions
Results The listbox's name on the root page Results
Other For templates Other
Navigate Footer hint after ↑ ↓ to navigate
Select Footer hint after Enter to select
Close Footer hint after Esc to close
ClearQuery Footer hint after Esc, inline to clear
Back Footer hint after Esc on a page to go back
OpenActions Footer hint after Tab for actions
Toggle Footer hint on a multi-select page to toggle
Apply Footer hint after Ctrl+Enter to apply
Pin Action panel Pin to top
Unpin Action panel Unpin
RemoveFromRecents Action panel Remove from recents
ClearRecents Action panel Clear recent commands
ConfirmPrefix Before an armed row's title, and its message in the footer Confirm:
ConfirmHint Announced when it is armed Press Enter again to confirm, Esc to cancel
SelectedCount Next to the box on a multi-select page {0} selected
ResultsAnnouncement Announced after a search {0} results available
OneResultAnnouncement Announced after a search 1 result available
NoResultsAnnouncement Announced after a search No results
PageAnnouncement Announced when a page opens: title, count {0}. {1}
Disabled The footer's answer to Enter on a disabled row without a reason Unavailable
ModeHintTitle For templates: a mode hint's title {0} — {1}
DialogLabel The dialog's name Command palette
InputLabel The search box's name Search commands
CloseButton The close button Close
BackButton The back button Back
Breadcrumb The breadcrumbs' name Breadcrumb
OpenPalette The trigger's name, after its label Open command palette
TriggerNameSeparator Joins the trigger's label and OpenPalette ,
Search The trigger's default label Search
Home The root page's title Home
MoreResults A source's next page, with the count left Show {0} more…
LoadMore A source's next page, count unknown Show more…
SequencePending The status after the first key of a sequence waiting for the next key…
CommandFailed A failed command Couldn’t run “{0}”.
LoadFailed A page that failed to load Couldn’t load this list.
Retry Its button Try again
ApproximateResults Over typo-tolerant results No exact matches. Showing close ones.
ApproximateResultsAnnouncement Announced with them: count, notice {0} {1}
Running Announced while a handler runs Working…
SourceFailed The row of a failed source Couldn’t search {0}
On A switch that is on (spoken) On
Off A switch that is off (spoken) Off
ShortcutThen Between the chords of a sequence then
An unhandled error has occurred. Reload 🗙