use-intl 2.7.6 → 2.8.0

package/src/{IntlProvider.tsx → core/IntlConfiguration.tsx}

@@ -1,14 +1,11 @@
-import React, {ReactNode, useEffect} from 'react';
-import AbstractIntlMessages from './AbstractIntlMessages';
 import Formats from './Formats';
-import IntlContext from './IntlContext';
 import IntlError from './IntlError';
-import {RichTranslationValues} from './TranslationValues';
-import validateMessages from './validateMessages';
 
-type Props = {
-  /** All messages that will be available in your components. */
-  messages?: AbstractIntlMessages;
+/**
+ * Should be used for entry points that configure the library.
+ */
+
+type IntlConfiguration = {
   /** A valid Unicode locale tag (e.g. "en" or "en-GB"). */
   locale: string;
   /** Global formats can be provided to achieve consistent
@@ -25,12 +22,10 @@ type Props = {
    * an error. This defaults to `${namespace}.${key}` You can use this to
    * customize what will be rendered in this case. */
   getMessageFallback?(info: {
-    namespace?: string;
-    key: string;
     error: IntlError;
+    key: string;
+    namespace?: string;
   }): string;
-  /** All components that use the provided hooks should be within this tree. */
-  children: ReactNode;
   /**
    * Providing this value will have two effects:
    * 1. It will be used as the default for the `now` argument of
@@ -41,47 +36,15 @@ type Props = {
    *    afterwards the current date will be returned continuously.
    */
   now?: Date;
-  /** Global default values for translation values and rich text elements.
-   * Can be used for consistent usage or styling of rich text elements.
-   * Defaults will be overidden by locally provided values. */
-  defaultTranslationValues?: RichTranslationValues;
 };
 
-function defaultGetMessageFallback({
-  key,
-  namespace
-}: {
-  key: string;
-  namespace?: string;
-}) {
-  return [namespace, key].filter((part) => part != null).join('.');
-}
-
-function defaultOnError(error: IntlError) {
-  console.error(error);
-}
-
-export default function IntlProvider({
-  children,
-  onError = defaultOnError,
-  getMessageFallback = defaultGetMessageFallback,
-  messages,
-  ...contextValues
-}: Props) {
-  if (__DEV__) {
-    // eslint-disable-next-line react-hooks/rules-of-hooks
-    useEffect(() => {
-      if (messages) {
-        validateMessages(messages, onError);
-      }
-    }, [messages, onError]);
-  }
+/**
+ * A stricter set of the configuration that should be used internally
+ * once defaults are assigned to `IntlConfiguration`.
+ */
+export type InitializedIntlConfiguration = IntlConfiguration & {
+  onError: NonNullable<IntlConfiguration['onError']>;
+  getMessageFallback: NonNullable<IntlConfiguration['getMessageFallback']>;
+};
 
-  return (
-    <IntlContext.Provider
-      value={{...contextValues, messages, onError, getMessageFallback}}
-    >
-      {children}
-    </IntlContext.Provider>
-  );
-}
+export default IntlConfiguration;

package/src/core/TranslationValues.tsx

@@ -0,0 +1,22 @@
+import {ReactNode} from 'react';
+
+// From IntlMessageFormat#format
+export type TranslationValue =
+  | string
+  | number
+  | boolean
+  | Date
+  | null
+  | undefined;
+
+type TranslationValues = Record<string, TranslationValue>;
+
+// We could consider renaming this to `ReactRichTranslationValues` and defining
+// it in the `react` namespace if the core becomes useful to other frameworks.
+// It would be a breaking change though, so let's wait for now.
+export type RichTranslationValues = Record<
+  string,
+  TranslationValue | ((chunks: ReactNode) => ReactNode)
+>;
+
+export default TranslationValues;

package/src/core/createBaseTranslator.tsx

@@ -0,0 +1,316 @@
+import IntlMessageFormat from 'intl-messageformat';
+import {
+  cloneElement,
+  isValidElement,
+  ReactElement,
+  ReactNode,
+  ReactNodeArray
+} from 'react';
+import AbstractIntlMessages from './AbstractIntlMessages';
+import Formats from './Formats';
+import {InitializedIntlConfiguration} from './IntlConfiguration';
+import IntlError, {IntlErrorCode} from './IntlError';
+import TranslationValues, {RichTranslationValues} from './TranslationValues';
+import convertFormatsToIntlMessageFormat from './convertFormatsToIntlMessageFormat';
+import {defaultGetMessageFallback, defaultOnError} from './defaults';
+import MessageKeys from './utils/MessageKeys';
+import NestedKeyOf from './utils/NestedKeyOf';
+import NestedValueOf from './utils/NestedValueOf';
+
+function resolvePath(
+  messages: AbstractIntlMessages | undefined,
+  key: string,
+  namespace?: string
+) {
+  if (!messages) {
+    throw new Error(
+      __DEV__ ? `No messages available at \`${namespace}\`.` : undefined
+    );
+  }
+
+  let message = messages;
+
+  key.split('.').forEach((part) => {
+    const next = (message as any)[part];
+
+    if (part == null || next == null) {
+      throw new Error(
+        __DEV__
+          ? `Could not resolve \`${key}\` in ${
+              namespace ? `\`${namespace}\`` : 'messages'
+            }.`
+          : undefined
+      );
+    }
+
+    message = next;
+  });
+
+  return message;
+}
+
+function prepareTranslationValues(values: RichTranslationValues) {
+  if (Object.keys(values).length === 0) return undefined;
+
+  // Workaround for https://github.com/formatjs/formatjs/issues/1467
+  const transformedValues: RichTranslationValues = {};
+  Object.keys(values).forEach((key) => {
+    let index = 0;
+    const value = values[key];
+
+    let transformed;
+    if (typeof value === 'function') {
+      transformed = (chunks: ReactNode) => {
+        const result = value(chunks);
+
+        return isValidElement(result)
+          ? cloneElement(result, {key: key + index++})
+          : result;
+      };
+    } else {
+      transformed = value;
+    }
+
+    transformedValues[key] = transformed;
+  });
+
+  return transformedValues;
+}
+
+export function getMessagesOrError<Messages extends AbstractIntlMessages>({
+  messages,
+  namespace,
+  onError = defaultOnError
+}: {
+  messages: Messages;
+  namespace?: string;
+  onError?(error: IntlError): void;
+}) {
+  try {
+    if (!messages) {
+      throw new Error(
+        __DEV__ ? `No messages were configured on the provider.` : undefined
+      );
+    }
+
+    const retrievedMessages = namespace
+      ? resolvePath(messages, namespace)
+      : messages;
+
+    if (!retrievedMessages) {
+      throw new Error(
+        __DEV__
+          ? `No messages for namespace \`${namespace}\` found.`
+          : undefined
+      );
+    }
+
+    return retrievedMessages;
+  } catch (error) {
+    const intlError = new IntlError(
+      IntlErrorCode.MISSING_MESSAGE,
+      (error as Error).message
+    );
+    onError(intlError);
+    return intlError;
+  }
+}
+
+export type CreateBaseTranslatorProps<Messages> =
+  InitializedIntlConfiguration & {
+    cachedFormatsByLocale?: Record<string, Record<string, IntlMessageFormat>>;
+    defaultTranslationValues?: RichTranslationValues;
+    namespace?: string;
+    messagesOrError: Messages | IntlError;
+  };
+
+export default function createBaseTranslator<
+  Messages extends AbstractIntlMessages,
+  NestedKey extends NestedKeyOf<Messages>
+>({
+  cachedFormatsByLocale,
+  defaultTranslationValues,
+  formats: globalFormats,
+  getMessageFallback = defaultGetMessageFallback,
+  locale,
+  messagesOrError,
+  namespace,
+  onError,
+  timeZone
+}: CreateBaseTranslatorProps<Messages>) {
+  function getFallbackFromErrorAndNotify(
+    key: string,
+    code: IntlErrorCode,
+    message?: string
+  ) {
+    const error = new IntlError(code, message);
+    onError(error);
+    return getMessageFallback({error, key, namespace});
+  }
+
+  function translateBaseFn(
+    /** Use a dot to indicate a level of nesting (e.g. `namespace.nestedLabel`). */
+    key: string,
+    /** Key value pairs for values to interpolate into the message. */
+    values?: RichTranslationValues,
+    /** Provide custom formats for numbers, dates and times. */
+    formats?: Partial<Formats>
+  ): string | ReactElement | ReactNodeArray {
+    if (messagesOrError instanceof IntlError) {
+      // We have already warned about this during render
+      return getMessageFallback({
+        error: messagesOrError,
+        key,
+        namespace
+      });
+    }
+    const messages = messagesOrError;
+
+    const cacheKey = [namespace, key].filter((part) => part != null).join('.');
+
+    let messageFormat;
+    if (cachedFormatsByLocale?.[locale]?.[cacheKey]) {
+      messageFormat = cachedFormatsByLocale?.[locale][cacheKey];
+    } else {
+      let message;
+      try {
+        message = resolvePath(messages, key, namespace);
+      } catch (error) {
+        return getFallbackFromErrorAndNotify(
+          key,
+          IntlErrorCode.MISSING_MESSAGE,
+          (error as Error).message
+        );
+      }
+
+      if (typeof message === 'object') {
+        return getFallbackFromErrorAndNotify(
+          key,
+          IntlErrorCode.INSUFFICIENT_PATH,
+          __DEV__
+            ? `Insufficient path specified for \`${key}\` in \`${
+                namespace ? `\`${namespace}\`` : 'messages'
+              }\`.`
+            : undefined
+        );
+      }
+
+      try {
+        messageFormat = new IntlMessageFormat(
+          message,
+          locale,
+          convertFormatsToIntlMessageFormat(
+            {...globalFormats, ...formats},
+            timeZone
+          )
+        );
+      } catch (error) {
+        return getFallbackFromErrorAndNotify(
+          key,
+          IntlErrorCode.INVALID_MESSAGE,
+          (error as Error).message
+        );
+      }
+
+      if (cachedFormatsByLocale) {
+        if (!cachedFormatsByLocale[locale]) {
+          cachedFormatsByLocale[locale] = {};
+        }
+        cachedFormatsByLocale[locale][cacheKey] = messageFormat;
+      }
+    }
+
+    try {
+      const formattedMessage = messageFormat.format(
+        // @ts-ignore `intl-messageformat` expects a different format
+        // for rich text elements since a recent minor update. This
+        // needs to be evaluated in detail, possibly also in regards
+        // to be able to format to parts.
+        prepareTranslationValues({...defaultTranslationValues, ...values})
+      );
+
+      if (formattedMessage == null) {
+        throw new Error(
+          __DEV__
+            ? `Unable to format \`${key}\` in ${
+                namespace ? `namespace \`${namespace}\`` : 'messages'
+              }`
+            : undefined
+        );
+      }
+
+      // Limit the function signature to return strings or React elements
+      return isValidElement(formattedMessage) ||
+        // Arrays of React elements
+        Array.isArray(formattedMessage) ||
+        typeof formattedMessage === 'string'
+        ? formattedMessage
+        : String(formattedMessage);
+    } catch (error) {
+      return getFallbackFromErrorAndNotify(
+        key,
+        IntlErrorCode.FORMATTING_ERROR,
+        (error as Error).message
+      );
+    }
+  }
+
+  function translateFn<
+    TargetKey extends MessageKeys<
+      NestedValueOf<Messages, NestedKey>,
+      NestedKeyOf<NestedValueOf<Messages, NestedKey>>
+    >
+  >(
+    /** Use a dot to indicate a level of nesting (e.g. `namespace.nestedLabel`). */
+    key: TargetKey,
+    /** Key value pairs for values to interpolate into the message. */
+    values?: TranslationValues,
+    /** Provide custom formats for numbers, dates and times. */
+    formats?: Partial<Formats>
+  ): string {
+    const result = translateBaseFn(key, values, formats);
+
+    if (typeof result !== 'string') {
+      return getFallbackFromErrorAndNotify(
+        key,
+        IntlErrorCode.INVALID_MESSAGE,
+        __DEV__
+          ? `The message \`${key}\` in ${
+              namespace ? `namespace \`${namespace}\`` : 'messages'
+            } didn't resolve to a string. If you want to format rich text, use \`t.rich\` instead.`
+          : undefined
+      );
+    }
+
+    return result;
+  }
+
+  translateFn.rich = translateBaseFn;
+
+  translateFn.raw = (
+    /** Use a dot to indicate a level of nesting (e.g. `namespace.nestedLabel`). */
+    key: string
+  ): any => {
+    if (messagesOrError instanceof IntlError) {
+      // We have already warned about this during render
+      return getMessageFallback({
+        error: messagesOrError,
+        key,
+        namespace
+      });
+    }
+    const messages = messagesOrError;
+
+    try {
+      return resolvePath(messages, key, namespace);
+    } catch (error) {
+      return getFallbackFromErrorAndNotify(
+        key,
+        IntlErrorCode.MISSING_MESSAGE,
+        (error as Error).message
+      );
+    }
+  };
+
+  return translateFn;
+}

package/src/{useIntl.tsx → core/createIntl.tsx}

@@ -1,7 +1,8 @@
 import DateTimeFormatOptions from './DateTimeFormatOptions';
+import Formats from './Formats';
 import IntlError, {IntlErrorCode} from './IntlError';
 import NumberFormatOptions from './NumberFormatOptions';
-import useIntlContext from './useIntlContext';
+import {defaultOnError} from './defaults';
 
 const MINUTE = 60;
 const HOUR = MINUTE * 60;
@@ -43,9 +44,21 @@ function getRelativeTimeFormatConfig(seconds: number) {
   return {value, unit};
 }
 
-export default function useIntl() {
-  const {formats, locale, now: globalNow, onError, timeZone} = useIntlContext();
-
+type Props = {
+  locale: string;
+  timeZone?: string;
+  onError?(error: IntlError): void;
+  formats?: Partial<Formats>;
+  now?: Date;
+};
+
+export default function createIntl({
+  formats,
+  locale,
+  now: globalNow,
+  onError = defaultOnError,
+  timeZone
+}: Props) {
   function resolveFormatOrOptions<Options>(
     typeFormats: Record<string, Options> | undefined,
     formatOrOptions?: string | Options

package/src/core/createTranslator.tsx

@@ -0,0 +1,112 @@
+import Formats from './Formats';
+import IntlConfiguration from './IntlConfiguration';
+import TranslationValues from './TranslationValues';
+import createTranslatorImpl, {
+  CoreRichTranslationValues
+} from './createTranslatorImpl';
+import {defaultGetMessageFallback, defaultOnError} from './defaults';
+import MessageKeys from './utils/MessageKeys';
+import NamespaceKeys from './utils/NamespaceKeys';
+import NestedKeyOf from './utils/NestedKeyOf';
+import NestedValueOf from './utils/NestedValueOf';
+
+/**
+ * Translates messages from the given namespace by using the ICU syntax.
+ * See https://formatjs.io/docs/core-concepts/icu-syntax.
+ *
+ * If no namespace is provided, all available messages are returned.
+ * The namespace can also indicate nesting by using a dot
+ * (e.g. `namespace.Component`).
+ */
+export default function createTranslator<
+  NestedKey extends NamespaceKeys<
+    IntlMessages,
+    NestedKeyOf<IntlMessages>
+  > = never
+>({
+  onError = defaultOnError,
+  getMessageFallback = defaultGetMessageFallback,
+  messages,
+  namespace,
+  ...rest
+}: IntlConfiguration & {
+  messages: IntlMessages;
+  namespace?: NestedKey;
+}): // Explicitly defining the return type is necessary as TypeScript would get it wrong
+{
+  // Default invocation
+  <
+    TargetKey extends MessageKeys<
+      NestedValueOf<
+        {'!': IntlMessages},
+        [NestedKey] extends [never] ? '!' : `!.${NestedKey}`
+      >,
+      NestedKeyOf<
+        NestedValueOf<
+          {'!': IntlMessages},
+          [NestedKey] extends [never] ? '!' : `!.${NestedKey}`
+        >
+      >
+    >
+  >(
+    key: TargetKey,
+    values?: TranslationValues,
+    formats?: Partial<Formats>
+  ): string;
+
+  // `rich`
+  rich<
+    TargetKey extends MessageKeys<
+      NestedValueOf<
+        {'!': IntlMessages},
+        [NestedKey] extends [never] ? '!' : `!.${NestedKey}`
+      >,
+      NestedKeyOf<
+        NestedValueOf<
+          {'!': IntlMessages},
+          [NestedKey] extends [never] ? '!' : `!.${NestedKey}`
+        >
+      >
+    >
+  >(
+    key: TargetKey,
+    values?: CoreRichTranslationValues,
+    formats?: Partial<Formats>
+  ): string;
+
+  // `raw`
+  raw<
+    TargetKey extends MessageKeys<
+      NestedValueOf<
+        {'!': IntlMessages},
+        [NestedKey] extends [never] ? '!' : `!.${NestedKey}`
+      >,
+      NestedKeyOf<
+        NestedValueOf<
+          {'!': IntlMessages},
+          [NestedKey] extends [never] ? '!' : `!.${NestedKey}`
+        >
+      >
+    >
+  >(
+    key: TargetKey
+  ): any;
+} {
+  // We have to wrap the actual function so the type inference for the optional
+  // namespace works correctly. See https://stackoverflow.com/a/71529575/343045
+  // The prefix ("!") is arbitrary.
+  return createTranslatorImpl<
+    {'!': IntlMessages},
+    [NestedKey] extends [never] ? '!' : `!.${NestedKey}`
+  >(
+    {
+      ...rest,
+      onError,
+      getMessageFallback,
+      messages: {'!': messages},
+      // @ts-ignore
+      namespace: namespace ? `!.${namespace}` : '!'
+    },
+    '!'
+  );
+}

package/src/core/createTranslatorImpl.tsx

@@ -0,0 +1,85 @@
+import AbstractIntlMessages from './AbstractIntlMessages';
+import {InitializedIntlConfiguration} from './IntlConfiguration';
+import IntlError, {IntlErrorCode} from './IntlError';
+import {RichTranslationValues, TranslationValue} from './TranslationValues';
+import createBaseTranslator, {getMessagesOrError} from './createBaseTranslator';
+import resolveNamespace from './resolveNamespace';
+import NestedKeyOf from './utils/NestedKeyOf';
+
+export type CoreRichTranslationValues = Record<
+  string,
+  TranslationValue | ((chunks: string) => string)
+>;
+
+export type CreateTranslatorImplProps<Messages> =
+  InitializedIntlConfiguration & {
+    namespace: string;
+    messages: Messages;
+  };
+
+export default function createTranslatorImpl<
+  Messages extends AbstractIntlMessages,
+  NestedKey extends NestedKeyOf<Messages>
+>(
+  {
+    getMessageFallback,
+    messages,
+    namespace,
+    onError,
+    ...rest
+  }: CreateTranslatorImplProps<Messages>,
+  namespacePrefix: string
+) {
+  // The `namespacePrefix` is part of the type system.
+  // See the comment in the function invocation.
+  messages = messages[namespacePrefix] as Messages;
+  namespace = resolveNamespace(namespace, namespacePrefix) as NestedKey;
+
+  const translator = createBaseTranslator<Messages, NestedKey>({
+    ...rest,
+    onError,
+    getMessageFallback,
+    messagesOrError: getMessagesOrError({
+      messages,
+      namespace,
+      onError
+    }) as Messages | IntlError
+  });
+
+  const originalRich = translator.rich;
+
+  function base(...args: Parameters<typeof translator>) {
+    return translator(...args);
+  }
+
+  // Augment `t.rich` to return plain strings
+  base.rich = (
+    key: Parameters<typeof originalRich>[0],
+    /** Key value pairs for values to interpolate into the message. */
+    values: CoreRichTranslationValues,
+    formats?: Parameters<typeof originalRich>[2]
+  ): string => {
+    // `chunks` is returned as a string when no React element
+    // is used, therefore it's safe to cast this type.
+    const result = originalRich(key, values as RichTranslationValues, formats);
+
+    // When only string chunks are provided to the parser, only strings should be returned here.
+    if (typeof result !== 'string') {
+      const error = new IntlError(
+        IntlErrorCode.FORMATTING_ERROR,
+        __DEV__
+          ? "`createTranslator` only accepts functions for rich text formatting that receive and return strings.\n\nE.g. t.rich('rich', {b: (chunks) => `<b>${chunks}</b>`})"
+          : undefined
+      );
+
+      onError(error);
+      return getMessageFallback({error, key, namespace});
+    }
+
+    return result;
+  };
+
+  base.raw = translator.raw;
+
+  return base;
+}

package/src/core/defaults.tsx

@@ -0,0 +1,18 @@
+import IntlError from './IntlError';
+
+/**
+ * Contains defaults that are used for all entry points into the core.
+ * See also `InitializedIntlConfiguration`.
+ */
+
+export function defaultGetMessageFallback(props: {
+  error: IntlError;
+  key: string;
+  namespace?: string;
+}) {
+  return [props.namespace, props.key].filter((part) => part != null).join('.');
+}
+
+export function defaultOnError(error: IntlError) {
+  console.error(error);
+}

package/src/core/index.tsx

@@ -0,0 +1,11 @@
+export {default as AbstractIntlMessages} from './AbstractIntlMessages';
+export {
+  default as TranslationValues,
+  RichTranslationValues
+} from './TranslationValues';
+export {default as Formats} from './Formats';
+export {default as DateTimeFormatOptions} from './DateTimeFormatOptions';
+export {default as NumberFormatOptions} from './NumberFormatOptions';
+export {default as IntlError, IntlErrorCode} from './IntlError';
+export {default as createTranslator} from './createTranslator';
+export {default as createIntl} from './createIntl';