feat(react,js): add locale option

Author: VojtechVidra

workspaces/js/src/init.ts

@@ -14,9 +14,16 @@ let locationChangeInterval: number | null = null;
 export const init = (options: FlowsOptions): void => {
   const apiUrl = options.apiUrl ?? "https://api.flows-cloud.com";
   config.value = { ...options, apiUrl };
-  const { environment, organizationId, userId, userProperties } = options;
+  const { environment, organizationId, userId, userProperties, locale } = options;
 
-  connectToWebsocketAndFetchBlocks({ apiUrl, environment, organizationId, userId, userProperties });
+  connectToWebsocketAndFetchBlocks({
+    apiUrl,
+    environment,
+    organizationId,
+    userId,
+    userProperties,
+    locale,
+  });
 
   if (locationChangeInterval !== null) clearInterval(locationChangeInterval);
   locationChangeInterval = window.setInterval(() => {

workspaces/js/src/lib/blocks.ts

@@ -1,4 +1,11 @@
-import { type BlockUpdatesPayload, getApi, log, type UserProperties } from "@flows/shared";
+import {
+  type BlockUpdatesPayload,
+  getApi,
+  getUserLocale,
+  type LocaleOption,
+  log,
+  type UserProperties,
+} from "@flows/shared";
 import { blocks } from "../store";
 import { type Disconnect, websocket } from "./websocket";
 import { packageAndVersion } from "./constants";
@@ -9,6 +16,7 @@ interface Props {
   organizationId: string;
   userId: string;
   userProperties?: UserProperties;
+  locale?: LocaleOption;
 }
 
 let disconnect: Disconnect | null = null;
@@ -23,7 +31,11 @@ export const connectToWebsocketAndFetchBlocks = (props: Props): void => {
 
   const fetchBlocks = (): void => {
     void getApi(apiUrl, packageAndVersion)
-      .getBlocks({ ...params, userProperties: props.userProperties })
+      .getBlocks({
+        ...params,
+        locale: getUserLocale(props.locale),
+        userProperties: props.userProperties,
+      })
       .then((res) => {
         blocks.value = res.blocks;
         // Disconnect if the user is usage limited

workspaces/js/src/types/configuration.ts

@@ -1,4 +1,4 @@
-import { type UserProperties } from "@flows/shared";
+import { type LocaleOption, type UserProperties } from "@flows/shared";
 
 export interface FlowsOptions {
   /**
@@ -21,4 +21,12 @@ export interface FlowsOptions {
    * Custom API URL useful when using proxy to send Flows requests through your own domain.
    */
   apiUrl?: string;
+  /**
+   * Locale used to select the correct translation for the block data.
+   * - `disabled` - the default language will be served. (default)
+   * - `automatic` - the locale will be detected from the browser settings.
+   * - specific locale (e.g. `en`, `en-US`) - The whole list of supported locales can be found: TODO:
+   * @defaultValue `disabled`
+   */
+  locale?: LocaleOption;
 }

workspaces/react/src/flows-provider.tsx

@@ -1,5 +1,5 @@
 import { type FC, type ReactNode } from "react";
-import { type UserProperties } from "@flows/shared";
+import { type LocaleOption, type UserProperties } from "@flows/shared";
 import { type TourComponents, type Components } from "./types";
 import { FlowsContext } from "./flows-context";
 import { useRunningTours } from "./hooks/use-running-tours";
@@ -40,6 +40,14 @@ export interface FlowsProviderProps {
    * Components used for tour blocks.
    */
   tourComponents: TourComponents;
+  /**
+   * Locale used to select the correct translation for the block data.
+   * - `disabled` - the default language will be served. (default)
+   * - `automatic` - the locale will be detected from the browser settings.
+   * - specific locale (e.g. `en`, `en-US`) - The whole list of supported locales can be found: TODO:
+   * @defaultValue `disabled`
+   */
+  locale?: LocaleOption;
 
   children: ReactNode;
 }
@@ -64,6 +72,7 @@ const FlowsProviderInner: FC<Props> = ({
   components,
   tourComponents,
   userProperties,
+  locale,
 }) => {
   globalConfig.apiUrl = apiUrl;
   globalConfig.environment = environment;
@@ -76,6 +85,7 @@ const FlowsProviderInner: FC<Props> = ({
     organizationId,
     userId,
     userProperties,
+    locale,
   });
 
   const runningTours = useRunningTours({ blocks, removeBlock });

workspaces/react/src/hooks/use-blocks.ts

@@ -6,6 +6,8 @@ import {
   type Block,
   type TourStep,
   type BlockUpdatesPayload,
+  type LocaleOption,
+  getUserLocale,
 } from "@flows/shared";
 import { packageAndVersion } from "../lib/constants";
 import { type RemoveBlock, type UpdateBlock } from "../flows-context";
@@ -17,6 +19,7 @@ interface Props {
   organizationId: string;
   userId: string;
   userProperties?: UserProperties;
+  locale?: LocaleOption;
 }
 
 interface Return {
@@ -31,6 +34,7 @@ export const useBlocks = ({
   organizationId,
   userId,
   userProperties,
+  locale,
 }: Props): Return => {
   const [blocks, setBlocks] = useState<Block[]>([]);
   const [usageLimited, setUsageLimited] = useState(false);
@@ -44,18 +48,21 @@ export const useBlocks = ({
     userPropertiesRef.current = userProperties;
   }, [userProperties]);
 
-  // TODO: call fetchBlocks on reconnect
   const fetchBlocks = useCallback(() => {
     void getApi(apiUrl, packageAndVersion)
-      .getBlocks({ ...params, userProperties: userPropertiesRef.current })
+      .getBlocks({
+        ...params,
+        locale: getUserLocale(locale),
+        userProperties: userPropertiesRef.current,
+      })
       .then((res) => {
         setBlocks(res.blocks);
         if (res.meta?.usage_limited) setUsageLimited(true);
       })
       .catch((err: unknown) => {
         log.error("Failed to load blocks", err);
       });
-  }, [apiUrl, params]);
+  }, [apiUrl, locale, params]);
 
   const websocketUrl = useMemo(() => {
     if (usageLimited) return;

workspaces/shared/src/api.ts

@@ -26,6 +26,7 @@ interface GetBlocksRequest {
   environment: string;
   organizationId: string;
   userProperties?: Record<string, unknown>;
+  locale?: string;
 }
 
 interface BlockResponseMeta {

workspaces/shared/src/index.ts

@@ -3,4 +3,5 @@ export * from "./component-props";
 export * from "./log";
 export * from "./matchers";
 export * from "./pathname";
+export * from "./locale";
 export * from "./types";

workspaces/shared/src/locale.ts

@@ -0,0 +1,10 @@
+import { type LocaleOption } from "./types";
+
+export const getUserLocale = (locale: LocaleOption = "disabled"): string | undefined => {
+  if (locale === "disabled") return undefined;
+  if (locale === "automatic") {
+    const browserLanguage = navigator.languages.at(0) ?? navigator.language;
+    return browserLanguage;
+  }
+  return locale;
+};

workspaces/shared/src/types/index.ts

@@ -1,5 +1,6 @@
 export * from "./active-block";
 export * from "./block";
 export * from "./components";
+export * from "./locale";
 export * from "./tooltip";
 export * from "./user-properties";