core: improve Translator type for strict TypeScript compatibility (#2562)

Fix #2528

- Replace overloaded Translator type with a generic conditional type
- Add createTranslator helper to allow implementation without type
  assertions under strictFunctionTypes and strictNullChecks.
- createTranslator always returns default value for undefined translation

Author: lucas-koehler

MIGRATION.md

@@ -2,6 +2,44 @@
 
 ## Migrating to JSON Forms 3.8
 
+### `Translator` type changed from overloaded signatures to a generic conditional type
+
+The `Translator` type was changed to improve compatibility with TypeScript's `strictFunctionTypes` and `strictNullChecks` compiler options (see [#2528](https://github.com/eclipsesource/jsonforms/issues/2528)).
+
+If you were previously assigning a function directly to the `Translator` type, this may no longer compile:
+
+```ts
+// No longer compiles
+const t: Translator = (id, defaultMessage) => defaultMessage ?? id;
+```
+
+Use the new `createTranslator` helper instead:
+
+```ts
+import { createTranslator } from '@jsonforms/core';
+
+const t = createTranslator((id, defaultMessage) => defaultMessage ?? id);
+```
+
+This also replaces the `as Translator` workaround that was previously needed under strict TypeScript settings.
+
+#### Vue: `Translator` return type in Options API
+
+If you have custom Vue renderers that access a `Translator` via `this` (Options API), the return type may no longer narrow to `string` even when a `defaultMessage` is provided.
+This is because Vue's ref unwrapping loses the generic parameter of the new conditional type.
+
+To fix this, use `as string` when you know a default message is always provided:
+
+```ts
+// Before (may now return string | undefined)
+return this.t(label, label);
+
+// After
+return this.t(label, label) as string;
+```
+
+This does not affect the Composition API where `Translator` is accessed directly from a `ComputedRef`.
+
 ### Angular material removes hammerjs
 
 The angular material package no longer depends or imports the `hammerjs` package.

packages/core/src/i18n/i18nUtil.ts

@@ -65,10 +65,25 @@ export const addI18nKeyToPrefix = (
   return `${i18nKeyPrefix}.${key}`;
 };
 
-export const defaultTranslator: Translator = (
-  _id: string,
-  defaultMessage: string | undefined
-) => defaultMessage;
+export const createTranslator =
+  (
+    fn: (
+      id: string,
+      defaultMessage: string | undefined,
+      values?: any
+    ) => string | undefined
+  ): Translator =>
+  (id: string, defaultMessage?: string, values?: any) => {
+    const translation = fn(id, defaultMessage, values);
+    if (translation === undefined) {
+      return defaultMessage;
+    }
+    return translation;
+  };
+
+export const defaultTranslator: Translator = createTranslator(
+  (_id, defaultMessage) => defaultMessage
+);
 
 export const defaultErrorTranslator: ErrorTranslator = (error, t, uischema) => {
   // check whether there is a special keyword message

packages/core/src/store/i18nTypes.ts

@@ -1,11 +1,11 @@
 import type { ErrorObject } from 'ajv';
 import type { JsonSchema, UISchemaElement } from '../models';
 
-export type Translator = {
-  (id: string, defaultMessage: string, values?: any): string;
-  (id: string, defaultMessage: undefined, values?: any): string | undefined;
-  (id: string, defaultMessage?: string, values?: any): string | undefined;
-};
+export type Translator = <D extends string | undefined = undefined>(
+  id: string,
+  defaultMessage?: D,
+  values?: any
+) => D extends string ? string : string | undefined;
 
 export type ErrorTranslator = (
   error: ErrorObject,

packages/examples/src/examples/arrays-with-translated-custom-element-label.ts

@@ -23,7 +23,7 @@
   THE SOFTWARE.
 */
 import { registerExamples } from '../register';
-import { JsonSchema7, Translator } from '@jsonforms/core';
+import { createTranslator, JsonSchema7, Translator } from '@jsonforms/core';
 
 export const data = {
   article: {
@@ -265,9 +265,9 @@ export const uischema = {
   ],
 };
 
-export const translate: Translator = (key: string) => {
+export const translate: Translator = createTranslator((key) => {
   return 'translator.' + key;
-};
+});
 
 registerExamples([
   {

packages/examples/src/examples/arraysI18n.ts

@@ -23,7 +23,11 @@
   THE SOFTWARE.
 */
 import { registerExamples } from '../register';
-import { ArrayTranslationEnum, Translator } from '@jsonforms/core';
+import {
+  ArrayTranslationEnum,
+  createTranslator,
+  Translator,
+} from '@jsonforms/core';
 import get from 'lodash/get';
 
 export const schema = {
@@ -88,9 +92,9 @@ export const translations = {
       'Are you sure you want to delete this comment?',
   },
 };
-export const translate: Translator = (key: string, defaultMessage: string) => {
+export const translate: Translator = createTranslator((key, defaultMessage) => {
   return get(translations, key) ?? defaultMessage;
-};
+});
 
 registerExamples([
   {

packages/examples/src/examples/categorization.ts

@@ -22,7 +22,7 @@
   OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
   THE SOFTWARE.
 */
-import { Translator } from '@jsonforms/core';
+import { createTranslator, Translator } from '@jsonforms/core';
 import get from 'lodash/get';
 import { registerExamples } from '../register';
 
@@ -292,9 +292,9 @@ export const translations = {
     label: 'Address',
   },
 };
-export const translate: Translator = (key: string, defaultMessage: string) => {
+export const translate: Translator = createTranslator((key, defaultMessage) => {
   return get(translations, key) ?? defaultMessage;
-};
+});
 
 registerExamples([
   {

packages/examples/src/examples/enumI18n.ts

@@ -23,7 +23,7 @@
   THE SOFTWARE.
 */
 import { registerExamples } from '../register';
-import { Translator } from '@jsonforms/core';
+import { createTranslator, Translator } from '@jsonforms/core';
 import get from 'lodash/get';
 
 export const schema = {
@@ -116,12 +116,9 @@ export const translations: Record<string, string> = {
   'status.rejected': 'Declined',
 };
 
-export const translate: Translator = (
-  key: string,
-  defaultMessage: string | undefined
-) => {
+export const translate: Translator = createTranslator((key, defaultMessage) => {
   return get(translations, key) ?? defaultMessage;
-};
+});
 
 registerExamples([
   {

packages/examples/src/examples/i18n.ts

@@ -30,6 +30,7 @@ import {
   AnyAction,
   Dispatch,
   Translator,
+  createTranslator,
 } from '@jsonforms/core';
 import get from 'lodash/get';
 import localize from 'ajv-i18n/localize';
@@ -99,9 +100,9 @@ export const translations = {
   },
   additionalInformationLabel: 'Additional Information',
 };
-export const translate: Translator = (key: string, defaultMessage: string) => {
+export const translate: Translator = createTranslator((key, defaultMessage) => {
   return get(translations, key) ?? defaultMessage;
-};
+});
 
 registerExamples([
   {

packages/material-renderers/test/renderers/util.ts

@@ -28,6 +28,7 @@ import {
   JsonFormsCore,
   JsonSchema,
   TesterContext,
+  createTranslator,
   Translator,
   UISchemaElement,
 } from '@jsonforms/core';
@@ -58,4 +59,6 @@ export const createTesterContext = (
   return { rootSchema, config };
 };
 
-export const testTranslator: Translator = (key: string) => 'translator.' + key;
+export const testTranslator: Translator = createTranslator(
+  (key) => 'translator.' + key
+);

packages/vue-vuetify/src/controls/DateControlRenderer.vue

@@ -384,14 +384,14 @@ const controlRenderer = defineComponent({
           ? this.appliedOptions.cancelLabel
           : 'Cancel';
 
-      return this.t(label, label);
+      return this.t(label, label) as string;
     },
     okLabel(): string {
       const label =
         typeof this.appliedOptions.okLabel == 'string'
           ? this.appliedOptions.okLabel
           : 'OK';
-      return this.t(label, label);
+      return this.t(label, label) as string;
     },
     showActions(): boolean {
       return this.appliedOptions.showActions === true;