Discussion: Alternative model to achieve type safe translations

[xdev1]

Localize already supports making translations type safe, at least up to a certain point.
But this might be a bit too cumbersome currently (I guess that's the reason why this feature has not been used in @shoelace-style/shoelace).

Please let me propose an alternative concept.
The concept could be implemented completely in user land, but if it was part of Localize or Shoelace we would have the same type safety for all (TS implemented) components in the SL universe, which would be a big win IMHO.

Main advantages:

• You cannot use any invalid translation keys in term(...) and this.localize.term(...), neither in the newly added (see below) function this.localize.t(...)

• The translation modules (e.g. file 'de.ts') are also completely type safe, you cannot use invalid translation keys. The types of all translation functions will automatically be inferred, independent whether you translate your own terms or terms of third-party SL-based components. You'll normally only need one simple type definition (=> FullTranslation<'someFancyLibrary'>, see below) to achieve full type safety in the translation files, the rest will be inferred.

• Uses categories/namespaces for terms, so no name collisions with name keys of different component libraries

Brief description of the concept:

• Type safe translations are mandatory not just optional (for TS)

• Translations are categorized, means EACH translation will belong to a dedicated category (call it "namespace" if you like).
  To achieve a better DX regarding code completion etc., category and term key will not be combined to a string (as in "someCategory:someKey") but passed separately to functions (as in 'someCategory', 'someKey')

• Each component will have its own term category/namespace

• Categories will be of type '${string}.${string}', for example "shoelace.colorPicker" (this will later turn out to be very useful)

• An additional mandatory argument category will be added to functions term and LocalizeController.prototype.term (don't worry, you will not use these functions very often)

• The constructor of LocalizeController will get a second mandatory argument category

• Class LocalizeController will be enhanced with a new translator method t(key, ...args), similar to term but without the need of passing the category (as the category has already been passed to the constructor). Method this.localize.term(...) is still there to have access to all translations (for example cross-cutting translations)

• It will turn out to make life much easier for the component developers if each component is always bundled with the en translations of its own terms (Shoelace is doing this already). This is not necessary, but very handy regarding DX.

• Localizable components will be implemented as follows:

  // color-picker.ts
  
  const translation: Translation = {
    $code: 'en',
    $name: 'English',   // frankly I've never understood what we need
    $dir: 'ltr',        // the meta information $name and $dir for
   
    'shoelace.colorPicker': {
      copy': 'Copy',
      currentValue': 'Current value',
      selectAColorFromTheScreen: 'Select a color from the screen',
      toggleColorFormat: 'Toggle color format'
    }
  };
  
  registerTranslation(translation);
  
  declare global {
    namespace Localize {
      interface TranslationsMap {
        'shoelace.colorPicker': TermsOf<typeof translation>
      }
    }
  }
   
  @customElement('sl-color-picker')
  export default class SlColorPicker extends LitElement {
    private localize = new LocalizeController(this, 'shoelace.colorPicker');
  
    ...
    
    render() {
      ...
      ... this.localize.t('toggleColorFormat') // this is properly typed
      ... this.localize.t('togleColorFormat')  // this will cause a type error      
      ...
    }
  }

  Translation file de.ts (btw: a en.ts file will not be needed):

  // de.ts
  
  import { registerTranslation, FullTranslation } form '@shoelace/localize';
  
  const translation: FullTranslation<'shoelace'> = {
     $code = 'de',
     $name = 'Deutsch',
     $dir = 'ltr',
  
    // It's important that translations for ALL shoelace terms
    // are provided here, otherwise it will cause type errors
    // due to `FullTranslation<'shoelace'>!
    // Use `PartialTranslation<'shoelace'>` if you only
    // want to provide a subset of the translations
    ...
    
    'shoelace.progressRing': {
       ...
    },
    
    ...
    
    'shoelace.colorPicker': {
      copy': 'Kopieren',
      currentValue': 'Aktueller Wert',
      selectAColorFromTheScreen: 'Wähle eine Farbe vom Bildschirm',
      toggleColorFormat: 'Farbformat umschalten'
    },
    ...
    // Arguments of translation functions will be
    // automatically inferred
    ...
  };
  
  registerTranslation(translation);
  
  export default translation;

• You may ask "But what about those terms that will be used in multiple components?"

  Either use a shared category, e.g. "shoelace.shared" (which I personally would normally not do, in most cases) or provide those terms independently for all involved components (this is what I would do).
  For example clearEntry is a term that is used for both SL components SlInput and SlSelect. The other day I've provided a PR for Shoelace with the German translation for clearEntry which is "Eingabe löschen". While "Eingabe löschen" is a good translation for the SlInput case, I would have preferred "Auswahl aufheben" (= "Clear selection") for the SlSelect case. So always using independent terms for different components may not be such a bad thing ("close" is another example: Why not allow to translate contextual to "Close dialog" and "Close tab"?).

[claviska]

"Discussions" are not activated so I open an issue for this.

Sorry about that. I guess discussions are disabled by default, even for newer repos. I've enabled them and converted the issue, since I use issues/PRs as a todo list and discussions aren't necessarily actionable items.

There are some cool ideas in here. It seems more like namespacing/grouping terms with a bit of type safety rolled in. I don't mean to sound dismissive, but this is a library that directly supports Shoelace, so its scope is tied to my immediate needs there. I don't want to spend my spare time refactoring this utility because I have other priorities I need to focus on.

Typed Translations and Arguments

That said, the 3.0 release of this utility makes strong typings easier to achieve by extending the LocalizeController and Translation interfaces. Internally, there's also a DefaultTranslation that's used if you choose not to extend. This interface has loose typings so any key/value will continue to work for users who aren't interested in strong typings.

import { LocalizeController as DefaultLocalizeController } from '@shoelace-style/localize';

// Extend the default controller with your custom translation
export class LocalizeController extends DefaultLocalizeController<MyTranslation> {}

// Export `registerTranslation` so you can import everything from this file
export { registerTranslation } from '@shoelace-style/localize';

// Define your translation terms here
export interface MyTranslation extends Translation {
  myTerm: string;
  myOtherTerm: string;
  myTermWithArgs: (count: string) => string;
}

With this, calls to this.localize.term() will be understood by TypeScript, including keys and arguments.

Merging Translations

Also new in 3.0 is the ability to merge translations of the same code, which was proposed in #7.

Removed Functions

The top level functions term(), date(), number(), and relativeTime() have been moved into the Reactive Controller. This reduces boilerplate, simplifies the codebase, and drastically reduces the complexity of type inheritance.

I realize this may be an unpopular decision for anyone who may have been using those methods. To be honest, I don't think I ever meant to expose them and I never even used them. This is the reason for the major version bump.

If you find the Reactive Controller pattern unacceptable, I would suggest forking 2.x and refactoring it as desired. Right now, I simply don't have the time to develop and maintain features and improvements that other people need for this utility.

As it stands, this micro library satisfies all the requirements I have for Shoelace, so I don't see any new features or refactors happening in the immediate future. I will, of course, continue to address bugs as they arise.

[xdev1]

I've deleted (hiding was not possible) my latest comment at is was just "saying thanks" to Cory for the latest changes in Localize, had not that much to do with the discussion itself.

@claviska
Seems I've been a couple of hours too early with my above proposal 😂
I've studied the way Localize v3.0.0 and Shoelace 2 Beta 75 are handling type safety for translations and I consider that a way better solution as my above proposal, mainly because of its simplicity.
Actually, I've implemented something similar to my above proposal a couple of month ago and am already using it, and I personally like that those translation types once defined are "just there" if needed without any additional interface imports 'n stuff... but be honest, many would consider this "too much magic" anyway 😉
The main issue with my proposal above would have been that types and type error messages were kinda complicated (manageable but complicated). This is no problem at all the way you've implemented things.

Nevertheless, namespaces are something to consider for 3rd-party component developers.
But the very easy trivial solution would be that component developers just add prefixes to all of their custom translation keys to prevent name collisions ... if only a few custom translations are needed than this will not be a problem at all, otherweise some helper functions in userland will do the trick, I guess.

Long story short: The above proposal is too complicated and kinda over the top ... so Cory, if possible please close, hide, delete it or whatever options there are, as there's no need for further discussion here.

BTW: Component libraries (including Shoelace) should always (!) export their translation types!