use-intl 2.7.6 → 2.7.7-alpha.0

package/src/{TranslationValues.tsx → core/TranslationValues.tsx}

@@ -1,13 +1,19 @@
 import {ReactNode} from 'react';
 
 // From IntlMessageFormat#format
-type TranslationValue = string | number | boolean | Date | null | undefined;
+export type TranslationValue =
+  | string
+  | number
+  | boolean
+  | Date
+  | null
+  | undefined;
 
 type TranslationValues = Record<string, TranslationValue>;
 
 export type RichTranslationValues = Record<
   string,
-  TranslationValue | ((children: ReactNode) => ReactNode)
+  TranslationValue | ((chunks: ReactNode) => ReactNode)
 >;
 
 export default TranslationValues;

package/src/core/config.tsx

@@ -0,0 +1,15 @@
+import IntlError from './IntlError';
+
+export function defaultGetMessageFallback({
+  key,
+  namespace
+}: {
+  key: string;
+  namespace?: string;
+}) {
+  return [namespace, key].filter((part) => part != null).join('.');
+}
+
+export function defaultOnError(error: IntlError) {
+  console.error(error);
+}

package/src/core/createBaseTranslator.tsx

@@ -0,0 +1,323 @@
+import IntlMessageFormat from 'intl-messageformat';
+import {
+  cloneElement,
+  isValidElement,
+  ReactElement,
+  ReactNode,
+  ReactNodeArray
+} from 'react';
+import AbstractIntlMessages from './AbstractIntlMessages';
+import Formats from './Formats';
+import IntlError, {IntlErrorCode} from './IntlError';
+import TranslationValues, {RichTranslationValues} from './TranslationValues';
+import {defaultGetMessageFallback, defaultOnError} from './config';
+import convertFormatsToIntlMessageFormat from './convertFormatsToIntlMessageFormat';
+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> = {
+  cachedFormatsByLocale?: Record<string, Record<string, IntlMessageFormat>>;
+  defaultTranslationValues?: RichTranslationValues;
+  formats?: Partial<Formats>;
+  getMessageFallback?(info: {
+    error: IntlError;
+    key: string;
+    namespace?: string;
+  }): string;
+  locale: string;
+  messagesOrError: Messages | IntlError;
+  namespace?: string;
+  onError(error: IntlError): void;
+  timeZone?: string;
+};
+
+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 './config';
 
 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,110 @@
+import Formats from './Formats';
+import TranslationValues from './TranslationValues';
+import createTranslatorImpl, {
+  CreateTranslatorImplProps,
+  CoreRichTranslationValues
+} from './createTranslatorImpl';
+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
+>({
+  messages,
+  namespace,
+  ...rest
+}: Omit<
+  CreateTranslatorImplProps<IntlMessages>,
+  'messagesOrError' | 'namespace' | 'namespacePrefix'
+> & {
+  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,
+      messages: {'!': messages},
+      // @ts-ignore
+      namespace: namespace ? `!.${namespace}` : '!'
+    },
+    '!'
+  );
+}

package/src/core/createTranslatorImpl.tsx

@@ -0,0 +1,95 @@
+import AbstractIntlMessages from './AbstractIntlMessages';
+import IntlError, {IntlErrorCode} from './IntlError';
+import {RichTranslationValues, TranslationValue} from './TranslationValues';
+import {defaultGetMessageFallback, defaultOnError} from './config';
+import createBaseTranslator, {
+  CreateBaseTranslatorProps,
+  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> = Omit<
+  CreateBaseTranslatorProps<Messages>,
+  'messagesOrError' | 'onError' | 'getMessageFallback' | 'namespace'
+> & {
+  messages: Messages;
+  onError?(error: IntlError): void;
+  getMessageFallback?(info: {
+    error: IntlError;
+    key: string;
+    namespace?: string;
+  }): string;
+  namespace: string;
+};
+
+export default function createTranslatorImpl<
+  Messages extends AbstractIntlMessages,
+  NestedKey extends NestedKeyOf<Messages>
+>(
+  {
+    messages,
+    namespace,
+    onError = defaultOnError,
+    getMessageFallback = defaultGetMessageFallback,
+    ...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,
+    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/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';

package/src/core/resolveNamespace.tsx

@@ -0,0 +1,12 @@
+/**
+ * For the strictly typed messages to work we have to wrap the namespace into
+ * a mandatory prefix. See https://stackoverflow.com/a/71529575/343045
+ */
+export default function resolveNamespace(
+  namespace: string,
+  namespacePrefix: string
+) {
+  return namespace === namespacePrefix
+    ? undefined
+    : namespace.slice((namespacePrefix + '.').length);
+}

package/src/index.tsx

@@ -1,15 +1,2 @@
-export {default as IntlProvider} from './IntlProvider';
-export {default as AbstractIntlMessages} from './AbstractIntlMessages';
-export {default as useTranslations} from './useTranslations';
-export {
-  default as TranslationValues,
-  RichTranslationValues
-} from './TranslationValues';
-export {default as useIntl} from './useIntl';
-export {default as useLocale} from './useLocale';
-export {default as useNow} from './useNow';
-export {default as useTimeZone} from './useTimeZone';
-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 * from './core';
+export * from './react';

package/src/{IntlContext.tsx → react/IntlContext.tsx}

@@ -1,8 +1,8 @@
 import {createContext} from 'react';
-import AbstractIntlMessages from './AbstractIntlMessages';
-import Formats from './Formats';
-import IntlError from './IntlError';
-import {RichTranslationValues} from './TranslationValues';
+import AbstractIntlMessages from '../core/AbstractIntlMessages';
+import Formats from '../core/Formats';
+import IntlError from '../core/IntlError';
+import {RichTranslationValues} from '../core/TranslationValues';
 
 export type IntlContextShape = {
   messages?: AbstractIntlMessages;