Localization for composites (Azure#595)

* renamed and exported locales. updated localization docs.

* comment update

* Change files

* fixed imports after rename

* Change files

* updated api.md files

* fixed locale options in storybook. fixed CustomLocale.snippet.

* addressed PR comments

* wording updated

* added errorBar strings in french

* exposed props for locale and wrapped composites internally with LocalizationProvider.

* updated fr_FR

* Composite localization doc added

* moved composite localization in Localization resource

* Change files

* moved localized composites snippet

* documentation and composite refactors

* moved localized composites snippet back

* @DefaultValue used in prop comments

Author: mgamis-msft

change/@internal-react-composites-fbbd34ed-0631-452d-ad33-ad9b9e6dc813.json

@@ -0,0 +1,7 @@
+{
+  "type": "prerelease",
+  "comment": "Exposed locale prop to localize composites.",
+  "packageName": "@internal/react-composites",
+  "email": "miguelgamis@microsoft.com",
+  "dependentChangeType": "patch"
+}

packages/communication-react/review/communication-react.api.md

@@ -335,6 +335,7 @@ export type CallCompositePage = 'configuration' | 'call' | 'error' | 'errorJoini
 export type CallCompositeProps = {
     adapter: CallAdapter;
     fluentTheme?: PartialTheme | Theme;
+    locale?: Locale;
     callInvitationURL?: string;
     onRenderAvatar?: (props: PlaceholderProps, defaultOnRender: (props: PlaceholderProps) => JSX.Element) => JSX.Element;
     identifiers?: Identifiers;
@@ -538,6 +539,7 @@ export type ChatCompositeClientState = {
 export type ChatCompositeProps = {
     adapter: ChatAdapter;
     fluentTheme?: PartialTheme | Theme;
+    locale?: Locale;
     onRenderAvatar?: (userId: string, avatarType?: 'chatThread' | 'participantList') => JSX.Element;
     onRenderMessage?: (messageProps: MessageProps, defaultOnRender?: DefaultMessageRendererType) => JSX.Element;
     onRenderTypingIndicator?: (typingUsers: CommunicationParticipant[]) => JSX.Element;

packages/react-composites/review/react-composites.api.md

@@ -23,6 +23,7 @@ import { DeviceManagerState } from '@internal/calling-stateful-client';
 import type { ErrorType } from '@internal/react-components';
 import { GroupCallLocator } from '@azure/communication-calling';
 import { Identifiers } from '@internal/react-components';
+import { Locale } from '@internal/react-components';
 import { MessageProps } from '@internal/react-components';
 import type { MicrosoftTeamsUserKind } from '@azure/communication-common';
 import { PartialTheme } from '@fluentui/react';
@@ -250,6 +251,7 @@ export type CallCompositePage = 'configuration' | 'call' | 'error' | 'errorJoini
 export type CallCompositeProps = {
     adapter: CallAdapter;
     fluentTheme?: PartialTheme | Theme;
+    locale?: Locale;
     callInvitationURL?: string;
     onRenderAvatar?: (props: PlaceholderProps, defaultOnRender: (props: PlaceholderProps) => JSX.Element) => JSX.Element;
     identifiers?: Identifiers;
@@ -343,6 +345,7 @@ export type ChatCompositeClientState = {
 export type ChatCompositeProps = {
     adapter: ChatAdapter;
     fluentTheme?: PartialTheme | Theme;
+    locale?: Locale;
     onRenderAvatar?: (userId: string, avatarType?: 'chatThread' | 'participantList') => JSX.Element;
     onRenderMessage?: (messageProps: MessageProps, defaultOnRender?: DefaultMessageRendererType) => JSX.Element;
     onRenderTypingIndicator?: (typingUsers: CommunicationParticipant[]) => JSX.Element;

packages/react-composites/src/composites/CallComposite/Call.tsx

@@ -11,16 +11,22 @@ import { CallAdapter, CallCompositePage } from './adapter/CallAdapter';
 import { IdentifierProvider, Identifiers, PlaceholderProps } from '@internal/react-components';
 import { useSelector } from './hooks/useSelector';
 import { getPage } from './selectors/baseSelectors';
-import { FluentThemeProvider } from '@internal/react-components';
+import { FluentThemeProvider, LocalizationProvider, Locale } from '@internal/react-components';
 
 export type CallCompositeProps = {
   adapter: CallAdapter;
   /**
    * Fluent theme for the composite.
    *
-   * Defaults to a light theme if undefined.
+   * @defaultValue `light theme`
    */
   fluentTheme?: PartialTheme | Theme;
+  /**
+   * Locale for the composite.
+   *
+   * @defaultValue `English (US)`
+   */
+  locale?: Locale;
   callInvitationURL?: string;
   onRenderAvatar?: (props: PlaceholderProps, defaultOnRender: (props: PlaceholderProps) => JSX.Element) => JSX.Element;
   identifiers?: Identifiers;
@@ -93,7 +99,7 @@ interface CallInternalProps extends CallCompositeProps {
  * @internal
  */
 export const CallCompositeInternal = (props: CallInternalProps): JSX.Element => {
-  const { adapter, callInvitationURL, fluentTheme, identifiers } = props;
+  const { adapter, callInvitationURL, fluentTheme, locale, identifiers } = props;
 
   useEffect(() => {
     (async () => {
@@ -104,7 +110,7 @@ export const CallCompositeInternal = (props: CallInternalProps): JSX.Element =>
     })();
   }, [adapter]);
 
-  return (
+  const callElement = (
     <FluentThemeProvider fluentTheme={fluentTheme}>
       <IdentifierProvider identifiers={identifiers}>
         <CallAdapterProvider adapter={adapter}>
@@ -117,4 +123,6 @@ export const CallCompositeInternal = (props: CallInternalProps): JSX.Element =>
       </IdentifierProvider>
     </FluentThemeProvider>
   );
+
+  return locale ? LocalizationProvider({ locale, children: callElement }) : callElement;
 };

packages/react-composites/src/composites/ChatComposite/ChatComposite.tsx

@@ -10,19 +10,27 @@ import {
   CommunicationParticipant,
   DefaultMessageRendererType,
   FluentThemeProvider,
+  LocalizationProvider,
   MessageProps,
   IdentifierProvider,
-  Identifiers
+  Identifiers,
+  Locale
 } from '@internal/react-components';
 
 export type ChatCompositeProps = {
   adapter: ChatAdapter;
   /**
    * Fluent theme for the composite.
    *
-   * Defaults to a light theme if undefined.
+   * @defaultValue `light theme`
    */
   fluentTheme?: PartialTheme | Theme;
+  /**
+   * Locale for the composite.
+   *
+   * @defaultValue `English (US)`
+   */
+  locale?: Locale;
   onRenderAvatar?: (userId: string, avatarType?: 'chatThread' | 'participantList') => JSX.Element;
   onRenderMessage?: (messageProps: MessageProps, defaultOnRender?: DefaultMessageRendererType) => JSX.Element;
   onRenderTypingIndicator?: (typingUsers: CommunicationParticipant[]) => JSX.Element;
@@ -56,10 +64,18 @@ export type ChatOptions = {
 };
 
 export const ChatComposite = (props: ChatCompositeProps): JSX.Element => {
-  const { adapter, fluentTheme, options, identifiers, onRenderAvatar, onRenderTypingIndicator, onRenderMessage } =
-    props;
+  const {
+    adapter,
+    fluentTheme,
+    locale,
+    options,
+    identifiers,
+    onRenderAvatar,
+    onRenderTypingIndicator,
+    onRenderMessage
+  } = props;
 
-  return (
+  const chatElement = (
     <FluentThemeProvider fluentTheme={fluentTheme}>
       <IdentifierProvider identifiers={identifiers}>
         <ChatAdapterProvider adapter={adapter}>
@@ -76,4 +92,6 @@ export const ChatComposite = (props: ChatCompositeProps): JSX.Element => {
       </IdentifierProvider>
     </FluentThemeProvider>
   );
+
+  return locale ? LocalizationProvider({ locale, children: chatElement }) : chatElement;
 };

packages/storybook/stories/Localization.stories.mdx

@@ -12,6 +12,7 @@ import TruncationSnippetText from '!!raw-loader!./snippets/localization/Truncati
 import { TruncationSnippet } from './snippets/localization/Truncation.snippet';
 import SetRTLSnippetText from '!!raw-loader!./snippets/localization/SetRTL.snippet';
 import { SetRTLForCanvasSnippet } from './snippets/localization/SetRTLForCanvas.snippet';
+import LocalizedComposites from '!!raw-loader!./snippets/localization/LocalizedComposites.snippet.tsx';
 
 <Meta id="localization" title="Localization" />
 
@@ -23,22 +24,28 @@ Developers can provide their own localization files to be used for the UI Librar
 
 ## LocalizationProvider
 
-`LocalizationProvider` is a component wrapper that sets all the strings for ACS components using a `Locale`. By default, all
+`LocalizationProvider` is a component wrapper that sets all the strings for UI Library components using a `Locale`. By default, all
 components use our English (US) locale. If desired, LocalizationProvider can be used to set a different locale. Out of the box,
 the UI library includes a set of locales usable with the UI components and composites
 
 ### Usage
 
-To use the LocalizationProvider, import it from `@azure/communication-react` and wrap it around ACS UI SDK components,
-For the example below, we will localize buttons in a `ControlBar` in French (France) by also importing locale `fr_FR` from
-`@azure/communication-react`.
+To use the LocalizationProvider, import it from `@azure/communication-react` and wrap it around UI Library components. Then assign a `Locale` to the `locale` prop.
+For the example below, we will localize buttons in a `ControlBar` in French (France) by also importing locale `fr_FR` from `@azure/communication-react`.
 
 <Source code={LocalizationProviderSnippetText} />
 
 <Canvas withSource="none">
   <LocalizationProviderSnippet />
 </Canvas>
 
+### Composites
+
+If you want to localize your composite, assign a `Locale` to the `locale` prop of the composite. You may import one of our locales like `fr_FR` for French (France)
+in the example below.
+
+<Source code={LocalizedComposites} />
+
 ## Overriding locales
 
 There are two options to customize the locales that we provide. For the examples below, let's say you wish to have a `ControlBar`
@@ -56,14 +63,14 @@ value `strings.cameraButton.offLabel` like shown below.
 </Canvas>
 
 `Locale` stores all strings in the `strings` property as a nested object. The component name is the first identifer and the string key is
-the second identifier such that each string can be accessed in this pattern `strings.<componentName>.<stringKey>`. If you are using typescript and
-have intellisense available in your IDE, it will be easy to discover all the strings.
+the second identifier such that each string can be accessed in this pattern `strings.<componentName>.<stringKey>`. If you are using
+typescript and have intellisense available in your IDE, it will be easy to discover all the strings.
 
 ### Option 2: Override `strings` prop in the UI Component
 
-The second option is to pass custom strings directly through the `strings` prop. Each component in ACS has an optional `strings`
-property that interfaces all strings that can be overriden in that component. There is no need to use `LocalizationProvider` because all components default
-to English (US). Just assign the string directly through `CameraButton` like shown below.
+The second option is to pass custom strings directly through the `strings` prop. Strings can be overriden for a UI Library
+component through the optional `strings` property. There is no need to use `LocalizationProvider` because all
+components default to English (US). Just assign the string directly through `CameraButton` like shown below.
 
 <Source code={StringsPropertySnippetText} />
 
@@ -92,14 +99,14 @@ We suggest the following options to achieve a better looking interface.
   <TruncationSnippet />
 </Canvas>
 
-Note: All ACS UI SDK components will have aria labels with the full text as part of our Accessibility promise.
+Note: All UI Library components will have aria labels with the full text as part of our Accessibility promise.
 
 3. Using styling to reduce font size.
 
 ## Setting RTL
 
 To set rtl in your web application, first import and call `setRTL` from `@fluentui/react` to set the root element's `dir` property to "rtl".
-All Azure Communication Services UI library components will be "flipped" just like the example `ControlBar` in Arabic below.
+All UI library components will be "flipped" just like the example `ControlBar` in Arabic below.
 
 <Source code={SetRTLSnippetText} />
 

packages/storybook/stories/QuickStarts/QuickstartComposite.stories.mdx

@@ -128,3 +128,4 @@ For more information, see the following resources:
 - [UI Library Use Cases](/?path=/story/use-cases--page)
 - [UI Library Styling](/?path=/story/styling--page)
 - [UI Library Theming](/?path=/story/theming--page)
+- [UI Library Localization](/?path=/story/localization--page#composites)

packages/storybook/stories/snippets/localization/LocalizedComposites.snippet.tsx

@@ -0,0 +1,75 @@
+import { AzureCommunicationTokenCredential } from '@azure/communication-common';
+import {
+  CallComposite,
+  CallAdapter,
+  createAzureCommunicationCallAdapter,
+  ChatComposite,
+  ChatAdapter,
+  createAzureCommunicationChatAdapter,
+  fr_FR
+} from '@azure/communication-react';
+import React, { useEffect, useMemo, useState } from 'react';
+
+function App(): JSX.Element {
+  const endpointUrl = '<Azure Communication Services Resource Endpoint>';
+  const userId = '<Azure Communication Services Identifier>';
+  const displayName = '<Display Name>';
+  const token = '<Azure Communication Services Access Token>';
+
+  //Calling Variables
+  //For Group Id, developers can pass any GUID they can generate
+  const groupId = '<Developer generated GUID>';
+  const [callAdapter, setCallAdapter] = useState<CallAdapter>();
+
+  //Chat Variables
+  const threadId = '<Get thread id from chat service>';
+  const [chatAdapter, setChatAdapter] = useState<ChatAdapter>();
+
+  // We can't even initialize the Chat and Call adapters without a well-formed token.
+  const credential = useMemo(() => {
+    try {
+      return new AzureCommunicationTokenCredential(token);
+    } catch {
+      console.error('Failed to construct token credential');
+      return undefined;
+    }
+  }, [token]);
+
+  useEffect(() => {
+    const createAdapter = async (): Promise<void> => {
+      setChatAdapter(
+        await createAzureCommunicationChatAdapter(
+          endpointUrl,
+          { kind: 'communicationUser', communicationUserId: userId },
+          displayName,
+          new AzureCommunicationTokenCredential(token),
+          threadId
+        )
+      );
+      setCallAdapter(
+        await createAzureCommunicationCallAdapter(
+          { kind: 'communicationUser', communicationUserId: userId },
+          displayName,
+          new AzureCommunicationTokenCredential(token),
+          { groupId }
+        )
+      );
+    };
+    createAdapter();
+  }, []);
+
+  if (!!callAdapter && !!chatAdapter) {
+    return (
+      <>
+        {chatAdapter && <ChatComposite adapter={chatAdapter} locale={fr_FR} />}
+        {callAdapter && <CallComposite adapter={callAdapter} locale={fr_FR} />}
+      </>
+    );
+  }
+  if (credential === undefined) {
+    return <h3>Failed to construct credential. Provided token is malformed.</h3>;
+  }
+  return <h3>Initializing...</h3>;
+}
+
+export default App;