Different steps of the Section Translation process (T243495) require language selection. This is an opportunity to create a standard language selection component in Vue that other products could reuse.
# Overview
The language selector shows a list of languages available for the user to select. Languages are listed using their name in their own language (i.e., the autonym). The number of languages provided in the selector is variable and can be potentially large. The selector supports searching, surfacing frequent languages, and adjusting the layout to the number of languages.
{F32367514, width=50%}
Overview of the selection process:
- **Open the selector.** The language selector opens after the user taps on an action (e.g., button) or selection (e.g., drop-down) control. The design of these entry points is out of the scope of the current task. A button can be used for testing purposes.
- **Search.** The user types a search query that filters the list of languages shown.
- **Select a language.** Taping on a language from the list completes the selection. Closing the selector automatically and making the selected value available to the product using the selector.
- **Close the selector.** The selector closes when taping outside the selector, pressing "esc" key or with a close action available on narrow screens. This cancels the selection.
{F32378436, width=50%}
# Responsive layout
The layout is adapted to the following factors:
**Number of languages**
- **0–9 languages.** Suggested languages are hidden. The list of languages has no label, and uses one column.
- **10-29 languages.** Suggested languages are shown using 2 columns. The list of languages uses one column. Both lists are labelled.
- **30 or more languages.** Suggested languages are shown. The lists of suggested and all languages use 3 columns (on wide screens). Additional space is added after each block of 5 rows.
|0–9 languages|10-29 languages|30-* languages|
|---|---|---|
|{F32378426}|{F32367547}|{F32367541}|
**Screen size**
- **Narrow screen.** The selector is shown as a full screen dialog. The list of all languages always uses one column.
- **Wider screen.** The selector is shown as a dialog over existing content. The list of all languages can use one or three columns depending on the number of languages (see above). The length of the selector will adapt to the available languages with a max height of 312px.
|Wide screen|Narrow screen|
|---|---|
|{F32367551}|{F32367553}
**Product preferences**
- **Option to hide suggested languages.** Suggested languages are shown by default when there are 10 languages or more available. However, this list is optional and apps have the option to hide the suggested languages list. In such case, the list of all languages will be shown without a title label.
The layout specifications for the different cases are captured below:
|{F32368862, size=full}|{F32368695, size=full}|
# Styling notes
Some notes on styling for the different pieces of the selector.
**Main panel**:
- Background: white (Base100)
- Border: 1px in Base70 with 2px radius.
- Shadow: Base0 at 25% opacity 1px down, 2px of blur
**Text styles**:
- Default: Standard body text (sans-serif 16 px in Base10)
- List title ("suggested", "All languages"): Base30
**Header:**
- Separator lines: 1px in Base70
**Search bar:**
- Shadow: Base0 at 25% opacity 1px down, 2px of blur
- Border radius: 2px radius on top corners, straight corners at the bottom.
**Hover and focus states**
{F32378440}
- Search bar focus state will use the 2px Accent50 border, the standard for input boxes.
- Language in the list are highlighted with a Base80 on hover.
# Search
We may want to reuse [[ https://wvui.netlify.app/ui/?path=/story/components-input--with-start-icon | existing search components ]].
Considerations for search:
- The search box gets the input focus automatically when the selector is opened.
- User input filters the list of languages based on prefix search as the user types. Search will be case insensitive. When searching, only the search results are displayed (no separate list for "suggested"). See example below.
- Searching should not change the dialog width. If a wide three-column version of the dialog is shown based on the large number of languages shown initially, searching should not result in the dialog to become narrow despite reducing the number of languages displayed. This avoids unnecessary distraction (as described in T286514).
- The search API for the current language selector can be reused to support flexible search capabilities (e.g., finding a language name written in any other language)
- Type-ahead autocompletion will add text after the search term to complete it when a matching language is found. For example, when typing "engli" the autocompletion text will show "sh" in grey to suggest "English" to the user.
- The search text is cleared when the selector gets closed. That is, previous searches should not remain visible when the selector is opened again.
{F32378432}
# Suggested languages
- The selector displays up to six suggested languages, using two or three columns depending on the number of languages (see responsive layout section).
- By default suggested languages
- Apps opening the selector can provide their own list of suggested languages, or hide the list.
- When suggested languages are not show (or the list is empty), the list of "all languages" will have its title hidden.
# Keyboard and pointer support
- "Esc" key would cancel the selection and close the selector.
- Arrow keys can be used to move through the options. The active item will be shown with a Base80 background.
- "Enter" would confirm the selection. Selecting the first results while searching, or the focused element while moving through the options.
- Hovering a language will show it with a Base80 background.
{F32368762}
# Sorting languages
Languages order considers their script and their label:
- Languages are ordered based on the alphabetical of their label (which is the autonym by default).
- All languages based on one script family are displayed before the languages of a different script. The order of the script families [[ https://github.com/wikimedia/language-data/blob/master/data/langdb.yaml#L692 | is defined in language data library ]].
Multiple columns use vertical lists:
- Columns are divided in blocks of 5 items listed vertically.
- Suggested languages area displays only 2 items per column since the area is limited to a total of six options.
- Once all columns are completed, a gap (24px) separates the next block of columns.
The ordering through multiple columns is organized to optimize the scan line. That is, reducing the number of [[ https://en.wikipedia.org/wiki/Saccade | saccades ]] (eyes jumping to the next line). This is illustrated in the image below:
{F34480446}
# Further context
This ticket covers only the basic aspects for the selector. Additional usecases requiring additional information, actions, or selection modes will be supported in separate tickets:
- {T265585}
- {T265996}
For a deep dive on how all these fit together you can check [[ https://commons.wikimedia.org/wiki/File:Language_Selector_Designs.pdf | this document ]].