core-app,plugin-api: update API reports + fixes

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

packages/core-app-api/alpha-api-report.md

@@ -5,32 +5,18 @@
 ```ts
 import { AppTranslationApi } from '@backstage/core-plugin-api/alpha';
 import { i18n } from 'i18next';
+import { TranslationMessages } from '@backstage/core-plugin-api/alpha';
 import { TranslationRef } from '@backstage/core-plugin-api/alpha';
+import { TranslationResource } from '@backstage/core-plugin-api/alpha';
 
 // @alpha (undocumented)
 export class AppTranslationApiImpl implements AppTranslationApi {
   // (undocumented)
-  addLazyResources<Messages extends Record<string, string>>(
-    translationRef: TranslationRef<Messages>,
-    initResources?: Record<
-      string,
-      () => Promise<{
-        messages: TranslationMessages<TranslationRef>;
-      }>
-    >,
-  ): void;
+  addLazyResources(resource: TranslationResource): void;
   // (undocumented)
-  addResources<Messages extends Record<string, string>>(
-    translationRef: TranslationRef<Messages>,
-    initResources?: Record<
-      string,
-      TranslationMessages<TranslationRef<Messages>>
-    >,
-  ): void;
+  addMessages(messages: TranslationMessages): void;
   // (undocumented)
-  addResourcesByRef<Messages extends Record<string, string>>(
-    translationRef: TranslationRef<Messages>,
-  ): void;
+  addResource(translationRef: TranslationRef): void;
   // (undocumented)
   static create(options?: ExperimentalI18n): AppTranslationApiImpl;
   // (undocumented)
@@ -39,47 +25,12 @@ export class AppTranslationApiImpl implements AppTranslationApi {
   initMessages(options?: ExperimentalI18n): void;
 }
 
-// @alpha (undocumented)
-export function createTranslationResource<T extends TranslationRef>(options: {
-  ref: T;
-  messages?: Record<string, TranslationMessages<T>>;
-  lazyMessages: Record<
-    string,
-    () => Promise<{
-      messages: TranslationMessages<T>;
-    }>
-  >;
-}): {
-  ref: T;
-  messages?: Record<string, TranslationMessages<T>> | undefined;
-  lazyMessages: Record<
-    string,
-    () => Promise<{
-      messages: TranslationMessages<T>;
-    }>
-  >;
-};
-
 // @alpha (undocumented)
 export type ExperimentalI18n = {
-  supportedLanguages: string[];
   fallbackLanguage?: string | string[];
-  messages?: Array<{
-    ref: TranslationRef;
-    messages?: Record<string, TranslationMessages<TranslationRef>>;
-    lazyMessages: Record<
-      string,
-      () => Promise<{
-        messages: TranslationMessages<TranslationRef>;
-      }>
-    >;
-  }>;
+  supportedLanguages?: string[];
+  resources?: Array<TranslationMessages | TranslationResource>;
 };
 
-// @alpha (undocumented)
-export type TranslationMessages<T> = T extends TranslationRef<infer R>
-  ? Partial<R>
-  : never;
-
 // (No @packageDocumentation comment for this package)
 ```

packages/core-app-api/api-report.md

@@ -64,7 +64,8 @@ import { SessionState } from '@backstage/core-plugin-api';
 import { StorageApi } from '@backstage/core-plugin-api';
 import { StorageValueSnapshot } from '@backstage/core-plugin-api';
 import { SubRouteRef } from '@backstage/core-plugin-api';
-import { TranslationRef } from '@backstage/core-plugin-api/alpha';
+import { TranslationMessages } from '@backstage/core-plugin-api/alpha';
+import { TranslationResource } from '@backstage/core-plugin-api/alpha';
 
 // @public
 export class AlertApiForwarder implements AlertApi {
@@ -221,19 +222,10 @@ export type AppOptions = {
   themes: (Partial<AppTheme> & Omit<AppTheme, 'theme'>)[];
   configLoader?: AppConfigLoader;
   bindRoutes?(context: { bind: AppRouteBinder }): void;
-  __experimentalI18n?: {
-    supportedLanguages: string[];
+  __experimentalTranslations?: {
     fallbackLanguage?: string | string[];
-    messages?: Array<{
-      ref: TranslationRef;
-      messages?: Record<string, TranslationMessages<TranslationRef>>;
-      lazyMessages: Record<
-        string,
-        () => Promise<{
-          messages: TranslationMessages<TranslationRef>;
-        }>
-      >;
-    }>;
+    supportedLanguages?: string[];
+    resources?: Array<TranslationMessages | TranslationResource>;
   };
 };
 

packages/core-app-api/src/app/AppManager.test.tsx

@@ -260,7 +260,7 @@ describe('Integration Test', () => {
     expect(screen.getByText('extLink4: <none>')).toBeInTheDocument();
   });
 
-  it('runs success with __experimentalI18n', async () => {
+  it('runs success with __experimentalTranslations', async () => {
     const app = new AppManager({
       apis: [noOpAnalyticsApi],
       defaultApis: [],
@@ -275,7 +275,7 @@ describe('Integration Test', () => {
           extRouteRef2: plugin2RouteRef,
         });
       },
-      __experimentalI18n: {
+      __experimentalTranslations: {
         supportedLanguages: ['en'],
       },
     });

packages/core-app-api/src/app/AppManager.tsx

@@ -179,7 +179,7 @@ export class AppManager implements BackstageApp {
     this.bindRoutes = options.bindRoutes;
     this.apiFactoryRegistry = new ApiFactoryRegistry();
     this.appTranslationApi = AppTranslationApiImpl.create(
-      options.__experimentalI18n,
+      options.__experimentalTranslations,
     );
   }
 

packages/core-app-api/src/app/types.ts

@@ -29,7 +29,6 @@ import {
 import { AppConfig } from '@backstage/config';
 import {
   TranslationMessages,
-  TranslationRef,
   TranslationResource,
 } from '@backstage/core-plugin-api/alpha';
 

packages/core-plugin-api/alpha-api-report.md

@@ -7,27 +7,64 @@ import { ApiRef } from '@backstage/core-plugin-api';
 import { BackstagePlugin } from '@backstage/core-plugin-api';
 import { i18n } from 'i18next';
 import { ReactNode } from 'react';
+import { TranslationMessages as TranslationMessages_2 } from '@backstage/core-plugin-api/alpha';
+import { TranslationRef as TranslationRef_2 } from '@backstage/core-plugin-api/alpha';
 
 // @alpha (undocumented)
 export type AppTranslationApi = {
   getI18n(): i18n;
-  addResourcesByRef<TMessages extends Record<string, string>>(
-    translationRef: TranslationRef<TMessages>,
-  ): void;
+  addResource(resource: TranslationRef): void;
 };
 
 // @alpha (undocumented)
 export const appTranslationApiRef: ApiRef<AppTranslationApi>;
 
-// @alpha (undocumented)
-export function createTranslationRef<
+// @alpha
+export function createTranslationMessages<
+  TId extends string,
   TMessages extends {
     [key in string]: string;
   },
-  TId extends string = string,
+  TFull extends boolean,
 >(
-  config: TranslationRefOptions<TMessages, TId>,
-): TranslationRef<TMessages, TId>;
+  options: TranslationMessagesOptions<TId, TMessages, TFull>,
+): TranslationMessages<TId, TMessages, TFull>;
+
+// @alpha (undocumented)
+export function createTranslationRef<
+  TId extends string,
+  TMessages extends {
+    [key in string]: string;
+  },
+  TTranslations extends {
+    [language in string]: () => Promise<{
+      default: {
+        [key in keyof TMessages]: string | null;
+      };
+    }>;
+  },
+>(
+  config: TranslationRefOptions<TId, TMessages, TTranslations>,
+): TranslationRef<TId, TMessages>;
+
+// @alpha (undocumented)
+export function createTranslationResource<
+  TId extends string,
+  TMessages extends {
+    [key in string]: string;
+  },
+  TTranslations extends {
+    [language in string]: () => Promise<{
+      default:
+        | TranslationMessages_2<TId>
+        | {
+            [key in keyof TMessages]: string | null;
+          };
+    }>;
+  },
+>(
+  options: TranslationResourceOptions<TId, TMessages, TTranslations>,
+): TranslationResource<TId>;
 
 // @alpha
 export interface PluginOptionsProviderProps {
@@ -40,17 +77,56 @@ export interface PluginOptionsProviderProps {
 // @alpha
 export const PluginProvider: (props: PluginOptionsProviderProps) => JSX.Element;
 
-// @alpha (undocumented)
-export interface TranslationOptions {}
-
-// @alpha (undocumented)
-export interface TranslationRef<
+// @alpha
+export interface TranslationMessages<
+  TId extends string = string,
   TMessages extends {
     [key in string]: string;
   } = {
     [key in string]: string;
   },
+  TFull extends boolean = boolean,
+> {
+  // (undocumented)
+  $$type: '@backstage/TranslationMessages';
+  full: TFull;
+  id: TId;
+  messages: TMessages;
+}
+
+// @alpha
+export interface TranslationMessagesOptions<
+  TId extends string,
+  TMessages extends {
+    [key in string]: string;
+  },
+  TFull extends boolean,
+> {
+  // (undocumented)
+  full?: TFull;
+  // (undocumented)
+  messages: false extends TFull
+    ? {
+        [key in keyof TMessages]?: string | null;
+      }
+    : {
+        [key in keyof TMessages]: string | null;
+      };
+  // (undocumented)
+  ref: TranslationRef_2<TId, TMessages>;
+}
+
+// @alpha (undocumented)
+export interface TranslationOptions {}
+
+// @alpha (undocumented)
+export interface TranslationRef<
   TId extends string = string,
+  TMessages extends {
+    [key in string]: string;
+  } = {
+    [key in string]: string;
+  },
 > {
   // (undocumented)
   $$type: '@backstage/TranslationRef';
@@ -62,24 +138,54 @@ export interface TranslationRef<
 
 // @alpha (undocumented)
 export interface TranslationRefOptions<
+  TId extends string,
   TMessages extends {
     [key in string]: string;
   },
-  TId extends string = string,
+  TTranslations extends {
+    [language in string]: () => Promise<{
+      default: {
+        [key in keyof TMessages]: string | null;
+      };
+    }>;
+  },
 > {
   // (undocumented)
   id: TId;
   // (undocumented)
-  lazyResources?: Record<
-    string,
-    () => Promise<{
-      messages: TMessages;
-    }>
-  >;
-  // (undocumented)
   messages: TMessages;
   // (undocumented)
-  resources?: Record<string, TMessages>;
+  translations?: TTranslations;
+}
+
+// @alpha (undocumented)
+export interface TranslationResource<TId extends string = string> {
+  // (undocumented)
+  $$type: '@backstage/TranslationResource';
+  // (undocumented)
+  id: TId;
+}
+
+// @alpha (undocumented)
+export interface TranslationResourceOptions<
+  TId extends string,
+  TMessages extends {
+    [key in string]: string;
+  },
+  TTranslations extends {
+    [language in string]: () => Promise<{
+      default:
+        | TranslationMessages_2<TId>
+        | {
+            [key in keyof TMessages]: string | null;
+          };
+    }>;
+  },
+> {
+  // (undocumented)
+  ref: TranslationRef_2<TId, TMessages>;
+  // (undocumented)
+  translations: TTranslations;
 }
 
 // @alpha
@@ -93,7 +199,7 @@ export const useTranslationRef: <
     [x: string]: string;
   },
 >(
-  translationRef: TranslationRef<TMessages, string>,
+  translationRef: TranslationRef<string, TMessages>,
 ) => <TKey extends keyof TMessages & string>(
   key: TKey,
   options?: TranslationOptions,