feat(i18n): add peristant language preference sync for authenticated users (#3325)

* feat(i18n): add peristant language preference sync for authenticated users

* feat(i18n): add user settings persistence configuration

* feat(i18n): add language preference documentation

* move user settings backend feature to new file

* select defeault language based on the broswer language

* add unit tests

* make i18n optional config

Author: karthikjeeyar

docs/customization.md

@@ -209,5 +209,46 @@ i18n:
     - en
     - de
     - it
-  defaultLocale: en # Optional. Defaults to `en` if not specified.
+  defaultLocale: en # Optional. Used as fallback when browser language preferences don't match supported locales, or defaults to 'en' if not specified.
 ```
+
+### Default Language Selection Priority
+
+Default language selection follows this priority order:
+
+1. **Browser Language Priority**: The system first checks the user's browser language preferences to provide a personalized experience.
+
+2. **Configuration Priority**: If no browser language matches the supported locales, the `defaultLocale` from the `i18n` configuration is used as a fallback.
+
+3. **Fallback Priority**: If neither browser preferences nor configuration provide a match, defaults to `en`.
+
+## Language Preferences
+
+Red Hat Developer Hub automatically saves and restores user language settings across browser sessions. This feature is enabled by default and uses database storage.
+
+### Configuration (Optional)
+
+Language preferences use database storage by default. To opt-out and use browser storage instead, add the following to your `app-config.yaml`:
+
+```yaml title="app-config.yaml"
+userSettings:
+  persistence: browser # opt-out of database storage
+```
+
+### Persistence Options
+
+- **`database`** (default): Stores language preferences in the backend database. Persists across devices and browsers. No configuration required.
+- **`browser`** (opt-out): Stores language preferences in browser local storage. Limited to single browser/device.
+
+## How It Works
+
+When users change the language in the UI:
+
+- The preference is automatically saved to storage
+- On next login/refresh, the language setting is restored
+- Guest users cannot persist language preferences
+
+## Usage
+
+1. Change language using any language selector in the UI
+2. Language setting will automatically be saved and restored

packages/app/config.d.ts

@@ -285,4 +285,15 @@ export interface Config {
      */
     defaultLocale?: string;
   };
+  /**
+   * Configuration options for your user settings.
+   * @deepVisibility frontend
+   */
+  userSettings?: {
+    /**
+     * The persistence mode for user settings.
+     * @visibility frontend
+     */
+    persistence: 'browser' | 'database';
+  };
 }

packages/app/src/apis.ts

@@ -1,22 +1,26 @@
-import { OAuth2 } from '@backstage/core-app-api';
+import { OAuth2, WebStorage } from '@backstage/core-app-api';
 import {
   AnyApiFactory,
   bitbucketAuthApiRef,
   configApiRef,
   createApiFactory,
   discoveryApiRef,
+  errorApiRef,
+  fetchApiRef,
   githubAuthApiRef,
   gitlabAuthApiRef,
   identityApiRef,
   microsoftAuthApiRef,
   oauthRequestApiRef,
+  storageApiRef,
 } from '@backstage/core-plugin-api';
 import {
   ScmAuth,
   scmAuthApiRef,
   ScmIntegrationsApi,
   scmIntegrationsApiRef,
 } from '@backstage/integration-react';
+import { UserSettingsStorage } from '@backstage/plugin-user-settings';
 
 import {
   auth0AuthApiRef,
@@ -29,6 +33,24 @@ import {
 } from './api/LearningPathApiClient';
 
 export const apis: AnyApiFactory[] = [
+  createApiFactory({
+    api: storageApiRef,
+    deps: {
+      discoveryApi: discoveryApiRef,
+      errorApi: errorApiRef,
+      fetchApi: fetchApiRef,
+      identityApi: identityApiRef,
+      configApi: configApiRef,
+    },
+    factory: deps => {
+      const persistence =
+        deps.configApi.getOptionalString('userSettings.persistence') ??
+        'database';
+      return persistence === 'browser'
+        ? WebStorage.create(deps)
+        : UserSettingsStorage.create(deps);
+    },
+  }),
   createApiFactory({
     api: scmIntegrationsApiRef,
     deps: { configApi: configApiRef },

packages/app/src/components/DynamicRoot/DynamicRoot.tsx

@@ -43,6 +43,7 @@ import extractDynamicConfig, {
   DynamicRoute,
 } from '../../utils/dynamicUI/extractDynamicConfig';
 import initializeRemotePlugins from '../../utils/dynamicUI/initializeRemotePlugins';
+import { getDefaultLanguage } from '../../utils/language/language';
 import { catalogTranslations } from '../catalog/translations/catalog';
 import { MenuIcon } from '../Root/MenuIcon';
 import CommonIcons from './CommonIcons';
@@ -563,7 +564,7 @@ export const DynamicRoot = ({
       app.current = createApp({
         __experimentalTranslations: {
           availableLanguages: translationConfig?.locales ?? ['en'],
-          defaultLanguage: translationConfig?.defaultLocale,
+          defaultLanguage: getDefaultLanguage(translationConfig),
           resources: [
             catalogTranslations,
             scaffolderTranslations,

packages/app/src/components/Root/Root.tsx

@@ -40,6 +40,7 @@ import DynamicRootContext, {
   ResolvedMenuItem,
 } from '@red-hat-developer-hub/plugin-utils';
 
+import { useLanguagePreference } from '../../hooks/useLanguagePreference';
 import { ApplicationHeaders } from './ApplicationHeaders';
 import { MenuIcon } from './MenuIcon';
 import { SidebarLogo } from './SidebarLogo';
@@ -297,6 +298,7 @@ export const Root = ({ children }: PropsWithChildren<{}>) => {
       permission: policyEntityCreatePermission,
       resourceRef: undefined,
     });
+  useLanguagePreference();
 
   const handleClick = (itemName: string) => {
     setOpenItems(prevOpenItems => ({