How should 3rd-party Shoelace component developers handle i18n?

[mcjazzyfunky]

If you are developing an app based on Shoelace, it's more or less up to you how to handle i18n.
But if you are writing a component library with additional Shoelace stylish components (like for example a date range picker etc.), it would be great if your components and other 3rd party Shoelace components handle i18n the same way, so that using different 3rd-party Shoelace components at the same time will still be fun, even regarding i18n.
How do you think this could and should be achieved (what about using Intl ... what about translation etc.)?
I would be happy to hear some comments and suggestions from the SL community regarding this subject 😃.

[claviska]

Right now, there aren't any components that require i18n in Shoelace (with the possible exception of sl-format-bytes, which was an oversight). This is something that still needs to be mapped out for more complex components, but for now it's a non-issue.

A few components already use Intl:

• sl-format-date
• sl-format-number
• sl-relative-time

Since localization is offloaded to the browser, these components are very lightweight. The default locale is whatever the browser is set to, but it can be customized using the locale prop.

There are only two components on my backlog that look like they'll require i18n:

• File Input ("Browse")
• Date Picker (months/days can be generated, but some terms cannot)

So I suspect I'll revisit this when that time comes. One option might be a prop like Duet's Date Picker uses:

picker.localization = {
  buttonLabel: "Valitse päivämäärä",
  placeholder: "pp.kk.vvvv",
  selectedDateMessage: "Valittu päivämäärä on",
  prevMonthLabel: "Edellinen kuukausi",
  nextMonthLabel: "Seuraava kuukausi",
  // ...
}

Since the number of Shoelace components that require localization will be few, I don't think we should force an opinion on how it should be handled in users' apps. There are many good libraries, particularly i18next, but what if you're using Rails or PHP? Or what if your app already has an established solution?

In that case, a prop is the most flexible since it can be set from any language and doesn't lock users into a specific i18n solution. Of course, I'm open to other ideas as well.

[mcjazzyfunky]

tl;dr: What follows is not urgent at all and can also be read/commented/discussed/ignored in weeks or moths - so no need to answer 😉

---

@claviska: Thanks for your response.

First some comments:

• The topic "i18n" does currently not seem to be very urgent in the SL community, I guess, otherwise someone else would have already addressed that issue. So no need to hurry. As you've written above "I'll revisit this when that time comes" ... sounds like a good plan 😉

• I opend this discussion because I hoped that maybe some folks will share their experience from other UI libraries or projects or whatever.

• I think it would be a terrible decision if some day in future SL would depend on one specific i18n library (my interpretation of your comment above is that you are of the same opinion).

• Also, it's important to notice that you never know for future apps whether the locale will be dictated by the browser or by the server or by a component somewhere up in the DOM tree etc.

• That picker.localization = {...} solution seems quite common, but if a 3rd-party SL component library provides dozens of localizable components and also some bigger localizable components that are a composite of smaller localizable components, then things will get more and more ugly ... developer experience will get worse.

I only have a very basic knowledge about i18n, so maybe the following proposal is a bit naive, but at least the idea would only add 1kB or whatever to SL core, by providing a core component sl-i18n and an abstract class Localizer in the following way (there's really no need to discuss this proposal right now - it's just to share my humble idea ... a discussion will only make sense after others also share their ideas):

1. The abstract class 'Localizer'

abstract class Localizer {
  static for(element: Element): Localizer {
    // In opposite of what's coming now, the following lines
    // should be somehow run lazy, means later, only on demand.
    // It's not really important what I mean with that
    // it's just that in the DatePicker example below
    // you'll see the line "private loc = Localizer.for(this)"
    // and this would not work if the following lines were
    // run before demand (especially not before `connectedCallback`).
    
    ... element.dispatchEvent(...) ...
    // more or less a call "Is there any localizer somewhere above in the DOM tree, then let me know"
    ...
    return foundLocalizer || defaultLocalizer // actually a bit more complicated - but not really important here.
    // the implementation of the default localizer should be as short as possible, yet useful.
    // Must only implement the most common cases for en_US (no external library needed!).
    // Can throw an error for non-common use-cases, IMHO.
  }
 
  // this interface is completely shoelace specific,
  // just a matter of taste, I guess.
  abstract formatDate(value: Date, format?: DateFormat): string
  abstract formatNumber(value: number, format?: NumberFormat): string
  abstract translate(key: string, replacements?: Record<string, any> | null, defaultText?: string): string
  abstract ...
  ...
}

2. A core Shoelace component <sl-18n ..> that could be used as follows:

  import { SlI18n, Localizer } from '@shoelace-style/shoelace'
  import { whateverI18nSetupFunction } from '@a-complete-third-party/somei18n-shoelace'
  // all i18n libraries are welcome!

  ...
  customElements.define('sl-i18n', SlI18n)
  ...
  const getLocalizer = whateverI18nSetupFunction(config)
  const localizer: Localizer = getLocalizer('fr_FR')
  ....
  
   
    <div>    
      // by default en_US is used here as locale (see: defaultLocalizer above)
      <thirdparty1-time-input/>
      <thirdparty1-time-range-input/>
      <thirdparty2-date-input/>
      <thirdparty3-calendar/>  
      
      
      <sl-i18n localizer={localizer}>   
        // this part will be using fr_FR
        <thirdparty1-time-input/>
        <thirdparty1-time-range-input/>
        <thirdparty2-date-input/>
        <thirdparty3-calendar/>  
      </sl-i18n>    
    </div>     

Third party component developers can use the follwowing pattern (they normally
will not need sl-i18n, as sl-i18n will normally only be used by app developers ):

import { Localizer } from '@shoelace-style/shoelace'
import { customElement, html, LitElement } from 'lit-element'

@customElement('thirdparty-user-stat')
class UserStat extends LitElement {
  private loc = Localizer.for(this)

  render() {
    ...
    const activeUserCount: number = ...
    const inactiveUserCount: number = ...
      
    const info = loc.translate(
      'some.component.namespace.infoAboutUsers',
      {
        numActiveUsers: loc.formatNumber(activeUserCount),
        numInactiveUsers: loc.formatNumber(inactiveUserCount)
      },
      'Number of active users: %{numActiveUsers}, '
        + 'number of inactive users: %{numInactiveUsers}'
    )
    
    return html`...${info}...`
  }
}