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.
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.
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.
| Property | Where | English |
|---|---|---|
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 |