agama-project / agama / 20262368863

push

github

web: added TranslatedString type (#2928)

## Problem

- We already check that the React components for untranslated string
literals, e.g. `<Button>Close</Button>` reports an error in the eslint
check.
- Unfortunately it cannot check the texts passed as a component
attribute, e.g. `<Button label="Close" />`

## Solution

- Use the [type-fest](https://www.npmjs.com/package/type-fest) library,
it provides quite a lot of useful TypeScript types
- Inspired by [this blog post
article](https://idmontie.github.io/blog/post/2023-08-19-localization)
- Define a new `TranslatedString` type which holds a translated string
(a string which passed through the `_()` or `n_()` translation
functions)
- Require this new type in some core components
- Passing a plain string where a TranslatedString is expected results in
a type error reported by TypeScript.

## Testing

- Updated unit tests

Tested with this small code snippet:
```tsx
function foo(label: TranslatedString) {
  return <>{label}</>;
}
// this line fails the type check
foo("label");
```

The last line in the example fails with error "Argument of type 'string'
is not assignable to parameter of type 'TranslatedString'.
  Type 'string' is not assignable to type 'Tag<"Translated", never>'."

## Notes

- The texts marked for translation in the unit tests are ignored when
building the POT file. Those strings are not uploaded to Weblate.

## Performance impact

The input TypeScript source code
```tsx
function foo(label: TranslatedString) {
  return <>{label}</>;
}
function bar() {
  return foo(_("label"));
}
```

Is compiled into this JavaScript:

```js
function foo(label) {
    return (0, jsx_runtime_1.jsx)(jsx_runtime_1.Fragment, { children: label });
}
function bar() {
    return foo((0, i18n_1._)("label"));
}
```

As you can see there is zero overhead for the `TranslatedString` type,
the check is completely done at the compile time without any performance
effect at runtime.

2695 of 4728 branches covered (57.0%)

Branch coverage included in aggregate %.

17 of 18 new or added lines in 13 files covered. (94.44%)

12158 of 16984 relevant lines covered (71.59%)

71.56 hits per line