RFC: i18n #419

claviska · 2021-04-16T14:31:55Z

It's time to start thinking about i18n. This discussion will be scoped to localization, whereas #191 will focus on RTL support.

There is a need for common labels in components that need to be localized. An example is in dialog/drawer/tab/tag, which all feature a built-in close button. Currently, the buttons don't have a label so screen readers don't announce them properly.

Important: I don't expect there to be many terms, nor do I want users to rely on Shoelace to power their app's localization. At this point in the library's development, a simple solution is preferred over a robust one.

Updated to reflect new requirements and information.

claviska · 2021-07-13T20:15:53Z

I'm trying to keep the discussion focused on a solution instead of hypotheticals so we don't get derailed. I feel like we're close and there have been some good suggestions in this thread.

Please don't take me hiding comments personally. 💙

claviska · 2021-12-06T16:55:06Z

Thanks again for all the discussions and ideas thus far. Trying to determine the best way to move forward with localization — without being too opinionated — has been an exhausting undertaking. This is one of the last remaining building blocks before a stable 2.0 can be released.

Here's a summary of the approach I've decided to take based on feedback, discussions, and experimentations throughout the year. First, a few things need to be clearly identified:

It's very rare (but not impossible) that a page will use more than one language
There's no efficient way to detect the current language or direction without expensive DOM traversal
The page language is always defined by <html lang="...">
Subsequent languages used on the page are defined using lang on specific elements, e.g. <sl-tab lang="es">

Based on this:

Shoelace components detect the locale using this.lang || document.documentElement.lang
- We are not honoring lang attributes on ancestor elements by design for performance reasons. That is, wrapping <div lang="..."> around a component will not localize the component.
Shoelace uses English as the default/fallback language. Additional translations can be imported by the consumer statically or dynamically.

Most of this doesn't matter to end users. What does matter to end users is how simple it is to load Shoelace in a specific language:

<html lang="es">
  <head>
    <link rel="stylesheet" href="/shoelace/dist/themes/light.css">
    <script type="module" src="/shoelace/dist/shoelace.js"></script>
    <script type="module" src="/shoelace/dist/translations/es.js"></script>
  </head>

  <body>
    ...
  </body>
</html>

In most cases, <html lang> is already set so the only thing 99.9% of users need to do is import their target language. If they update <html lang>, all localized components will update automatically.

That said, I've released 2.0 of @shoelace-style/localize which uses the Reactive Controller pattern. This results in a small, elegant DX for component developers.

Here's a Lit component localizing a term, date, and number:

import { LitElement } from 'lit';
import { customElement } from 'lit/decorators.js';
import { LocalizeController } from '@shoelace-style/localize/dist/lit.js';

@customElement('my-element')
export class MyElement extends LitElement {
  private localize = new LocalizeController(this);

  @property() lang: string;

  render() {
    return html`
      <!-- Term -->
      ${this.localize.term('hello')}

      <!-- Date -->
      ${this.localize.date('2021-09-15 14:00:00 ET'), { month: 'long', day: 'numeric', year: 'numeric' }}

      <!-- Number/currency -->
      ${this.localize.number(1000, { style: 'currency', currency: 'USD'})}
    `;
  }
}

I've already implemented these changes in a local branch and I'm finishing up documentation before merging it into next. I expect to have all existing components fully localized in the next day or two.

claviska · 2021-12-07T22:17:19Z

I'm closing this since localization has been implemented. There's still work to be done to support RTL languages, but the scope of this issue is complete finally.

claviska added this to the v2.0.0 release milestone Apr 16, 2021

claviska self-assigned this Apr 16, 2021

claviska added the i18n Anything related to internationalization. label Apr 16, 2021

This comment has been minimized.

Sign in to view

mcjazzyfunky mentioned this issue Jul 1, 2021

sl-datepicker component #474

Closed

This comment has been minimized.

Sign in to view

hanc2006 added a commit to hanc2006/shoelace that referenced this issue Jul 23, 2021

shoelace-style#419 i18n single locale with lit directive

00519ec

This comment has been minimized.

Sign in to view

This was referenced Jul 23, 2021

#419 added single locale support with lit directive #487

Closed

#419 added sl-locale component with support for multiple languages #488

Closed

claviska unpinned this issue Aug 10, 2021

This comment has been minimized.

Sign in to view

mcjazzyfunky mentioned this issue Aug 29, 2021

added sl-date-picker component #486

Closed

claviska pinned this issue Sep 10, 2021

claviska mentioned this issue Oct 14, 2021

test: components/progress-bar components/progress-ring #562

Merged

SuaYoo mentioned this issue Nov 20, 2021

Add frontend localization support webrecorder/browsertrix#18

Merged

claviska closed this as completed Dec 7, 2021

claviska unpinned this issue Dec 7, 2021

claviska mentioned this issue Jun 9, 2022

Mechanism for detecting RTL inside components #773

Closed

RFC: i18n #419

RFC: i18n #419

Comments

claviska commented Apr 16, 2021 • edited

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

claviska commented Jul 13, 2021

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

claviska commented Dec 6, 2021

claviska commented Dec 7, 2021

claviska commented Apr 16, 2021 •

edited