- Home
- Design system
- Web components
- Language
Language
DS Language web component for selecting English or Japanese
Overview
ds-language is a Web Component that renders English and Japanese as a side-by-side SDS language selector. It resolves the initial language, keeps the selected option and <html lang> synchronized, persists explicit selections in a cookie, and navigates user selections through the lang query parameter.
Use it wherever an application needs to expose the shared Soracom language preference. The component does not use localStorage.
Usage
Import the component once, then place <ds-language> where the selector should appear.
The live example uses a separate cookie name so it does not replace the standard sc-lang preference.
Use the default cookie name in product code.
Language resolution
When it connects, ds-language uses the first supported value from the following sources:
- The
langquery parameter. - The
sc-langcookie, or the cookie selected bycookie-name. - A supported
<html lang>value. -
navigator.languages, followed bynavigator.language. - English.
English and Japanese regional language tags are normalized to en and ja. For example, en-GB resolves to en and ja-JP resolves to ja.
An unsupported query value is ignored. When a supported query value differs from the current cookie, the component writes the normalized value to the cookie. It does not remove the query parameter from the URL; the host application remains responsible for URL canonicalization.
Navigation
Selecting a language through the control navigates to the current URL with lang=en or lang=ja. Existing query parameters and the URL fragment are preserved. This reloads server-rendered applications so they can resolve the language before rendering; the server can then redirect to the canonical URL without lang.
Setting the JavaScript value property updates the component, document language, and cookie without navigating.
Persistence
Explicit changes are stored in the sc-lang cookie by default. Set cookie-name when an embedded or isolated selector needs separate persistence.
The cookie is written for the shared parent domain on soracom.io, soracom.jp, and app.localhost. Other hosts receive a host-only cookie. It uses a one-year maximum age and the root path.
Document synchronization
Selecting a language updates <html lang> with the normalized en or ja value. Multiple ds-language instances stay synchronized through this document attribute.
If application code changes <html lang> to a supported language, the component updates its selected option without writing the cookie or dispatching an event. Applications that use <html lang> as their locale integration point can read the initial value and monitor it for changes.
Events
ds-language dispatches ds-language-change for an explicit selection made through the control or its value API. For control selections, the event is dispatched before navigation. Initial resolution and external <html lang> changes do not dispatch the event.
The event bubbles, crosses a shadow boundary, and provides { value: "en" | "ja" } in detail.
Attributes
| Attribute | Values | Default | Description |
|---|---|---|---|
value | en, ja | Resolved language | Reflects the current normalized language. Setting it after initialization updates <html lang>, persists the selection, and dispatches ds-language-change. |
cookie-name | Cookie name string | sc-lang | Sets the cookie used to read and persist the language preference. |
aria-label | Accessible name string | Localized Language label | Overrides the accessible name of the internal language navigation. |
css | global, shadow | global | Uses global SDS CSS by default. Set to shadow to load the required SDS styles into Shadow DOM. |
The JavaScript value property accepts en or ja. Unsupported values are ignored and do not change the current selection.
Accessibility
ds-language renders native links in labelled navigation with the SDS language icon. Both language names remain visible, and aria-current="true" exposes the selected language without causing navigation while keyboard users move between controls.
Each option carries its own language metadata: English uses lang="en", and 日本語 uses lang="ja".
Angular usage
ds-language is a standard Web Component and works in Angular templates like any other native element.
Registering the element
Import the component once at application startup.
Allowing the tag in templates
Add CUSTOM_ELEMENTS_SCHEMA to every NgModule whose templates use <ds-language> or to standalone components through schemas.
Usage example
Angular custom event binding can receive explicit language selections. The application can also monitor <html lang> when it needs to react to every supported document-language change.
Manifest
The component manifest describes this component's API: its modifiers, structure, data attributes, CSS custom properties, accessibility notes, and example markup. It is consumed by tooling such as AI assistants and code generators.
Latest version: https://assets.soracom.io/sds/3.39.6/ds-language/manifest.json?v=3.39.6