Function.usePreferredLocaleSync

function usePreferredLocaleSync<T>(options: UsePreferredLocaleSyncOptions<T>): void;

Synchronizes the application locale with the user's stored locale preference from the server.

This hook reads the authenticated user's preferredLocale via useKeybanAuth(), validates it against the app's supported locales, and applies it via the provided callback. It runs on app load and whenever the user's preference changes (e.g., after login with a different user).

Requirements: The component must be wrapped with KeybanAuthProvider for this hook to work.

The locale is only applied if:

1. A user is authenticated
2. The stored preference is a non-null string
3. The preference exists in the app's supportedLocales

If the user's preferredLocale is not in supportedLocales, it is silently ignored and the app keeps its current (localStorage / default) preference. This allows multi-app deployments where different apps ship different locale subsets (e.g. an es-ES preference set in the DPP app is ignored by an app that only ships fr-FR/en-US).

For apps without KeybanAuthProvider: Use usePreferredLocaleSyncWithUser instead.

Type Parameters

Type Parameter	Default type
T extends string	string

Parameters

Parameter	Type	Description
options	UsePreferredLocaleSyncOptions<T>	Configuration for locale syncing

Returns

void

Example

function AppRoot() {
  const { setLocale } = useLocaleContext();
  usePreferredLocaleSync({
    supportedLocales: ['en-US', 'fr-FR', 'es-ES'],
    onLocaleChange: setLocale,
  });
  return <App />;
}