@discord/intl 0.0.1

package/dist/message.js

@@ -0,0 +1,148 @@
+"use strict";
+var __values = (this && this.__values) || function(o) {
+    var s = typeof Symbol === "function" && Symbol.iterator, m = s && o[s], i = 0;
+    if (m) return m.call(o);
+    if (o && typeof o.length === "number") return {
+        next: function () {
+            if (o && i >= o.length) o = void 0;
+            return { value: o && o[i++], done: !o };
+        }
+    };
+    throw new TypeError(s ? "Object is not iterable." : "Symbol.iterator is not defined.");
+};
+var __read = (this && this.__read) || function (o, n) {
+    var m = typeof Symbol === "function" && o[Symbol.iterator];
+    if (!m) return o;
+    var i = m.call(o), r, ar = [], e;
+    try {
+        while ((n === void 0 || n-- > 0) && !(r = i.next()).done) ar.push(r.value);
+    }
+    catch (error) { e = { error: error }; }
+    finally {
+        try {
+            if (r && !r.done && (m = i["return"])) m.call(i);
+        }
+        finally { if (e) throw e.error; }
+    }
+    return ar;
+};
+var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InternalIntlMessage = void 0;
+var icu_messageformat_parser_1 = require("@formatjs/icu-messageformat-parser");
+var intl_messageformat_1 = require("intl-messageformat");
+var InternalIntlMessage = /** @class */ (function () {
+    function InternalIntlMessage(messageOrAst, locale) {
+        this.locale = locale;
+        if (typeof messageOrAst === 'string') {
+            // TODO: This part should pre-parse our Markdown shorthand, too, so that
+            // the AST that comes out of this is a standardized format, and we don't
+            // have to do any special handling after calling `format`. That also
+            // removes the need for handling "unsafe" values, since they'll be
+            // parsed before values get interpolated. We can actually do that in the
+            // loader, too, and avoid any runtime cost for it.
+            this.message = messageOrAst;
+            this.ast = (0, icu_messageformat_parser_1.parse)(messageOrAst);
+        }
+        else {
+            this.ast = messageOrAst;
+        }
+        this.plainAst = undefined;
+    }
+    /**
+     * Format this message with the given locale into an AST of chunks that can
+     * then be used or rendered into strings, React elements, or anything else as
+     * needed.
+     */
+    InternalIntlMessage.prototype.formatToParts = function (formatters, formats, values) {
+        return (0, intl_messageformat_1.formatToParts)(this.ast, this.locale, formatters, formats, values);
+    };
+    /**
+     * Formats this message just like `formatToParts`, but strips all stylistic
+     * elements and tags and returns a plain string with only the literal text of
+     * the message remaining.
+     *
+     * This method works by quickly scanning the string and removing any tag
+     * elements, formatting, then concatenating the pieces into a single result.
+     *
+     * Note that this function does _not_ handle serializing values other than
+     * plain/primitive values into strings. All values are simply converted using
+     * the `String()` constructor. So, for example, passing a function as a value
+     * will directly serialize the function definition into a string, rather than
+     * calling the function or evaluating the result.
+     */
+    InternalIntlMessage.prototype.formatToPlainString = function (formatters, formats, values) {
+        var e_1, _a, _b, e_2, _c;
+        // Lazily create the reduced AST if it hasn't already been done.
+        if (this.plainAst == null) {
+            this.plainAst = [];
+            try {
+                for (var _d = __values(this.ast), _e = _d.next(); !_e.done; _e = _d.next()) {
+                    var part = _e.value;
+                    (_b = this.plainAst).push.apply(_b, __spreadArray([], __read(this._removeRichTags(part)), false));
+                }
+            }
+            catch (e_1_1) { e_1 = { error: e_1_1 }; }
+            finally {
+                try {
+                    if (_e && !_e.done && (_a = _d.return)) _a.call(_d);
+                }
+                finally { if (e_1) throw e_1.error; }
+            }
+        }
+        var parts = (0, intl_messageformat_1.formatToParts)(this.plainAst, this.locale, formatters, formats, values);
+        var result = '';
+        try {
+            for (var parts_1 = __values(parts), parts_1_1 = parts_1.next(); !parts_1_1.done; parts_1_1 = parts_1.next()) {
+                var part = parts_1_1.value;
+                result += String(part.value);
+            }
+        }
+        catch (e_2_1) { e_2 = { error: e_2_1 }; }
+        finally {
+            try {
+                if (parts_1_1 && !parts_1_1.done && (_c = parts_1.return)) _c.call(parts_1);
+            }
+            finally { if (e_2) throw e_2.error; }
+        }
+        return result;
+    };
+    /**
+     * Returns the same element with any formatting tags removed. If the element
+     * itself is a tag, the children will be hoisted and returned, otherwise the
+     * element is returned as an array of itself.
+     */
+    InternalIntlMessage.prototype._removeRichTags = function (element) {
+        var e_3, _a;
+        if (element.type === icu_messageformat_parser_1.TYPE.tag) {
+            var childContent = [];
+            try {
+                for (var _b = __values(element.children), _c = _b.next(); !_c.done; _c = _b.next()) {
+                    var child = _c.value;
+                    childContent.push.apply(childContent, __spreadArray([], __read(this._removeRichTags(child)), false));
+                }
+            }
+            catch (e_3_1) { e_3 = { error: e_3_1 }; }
+            finally {
+                try {
+                    if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+                }
+                finally { if (e_3) throw e_3.error; }
+            }
+            return childContent;
+        }
+        else {
+            return [element];
+        }
+    };
+    return InternalIntlMessage;
+}());
+exports.InternalIntlMessage = InternalIntlMessage;

package/dist/react.d.ts

@@ -0,0 +1,24 @@
+import * as React from 'react';
+import { IntlManager } from './intl-manager';
+import type { FormatValuesFor, RichTextElementMap, TypedIntlMessageGetter } from './types';
+export declare class IntlManagerReact<DefaultElements extends RichTextElementMap, DefaultValues extends keyof DefaultElements> extends IntlManager<DefaultElements, DefaultValues> {
+    /**
+     * A reactive component form of `intl.format` that automatically updates when
+     * the application's locale changes and when new data is loaded for the
+     * subject message.
+     */
+    IntlMessage: <T extends TypedIntlMessageGetter<object | undefined>>(props: {
+        message: T;
+        values?: Omit<FormatValuesFor<T>, DefaultValues>;
+    }) => React.FunctionComponentElement<{
+        children?: React.ReactNode | undefined;
+    }>;
+    /**
+     * Format the given message as a React component, allowing it to listen for
+     * and respond to updates about the current locale and other relevant
+     * information.
+     */
+    format<T extends TypedIntlMessageGetter<object | undefined>>(message: T): JSX.Element;
+    format<T extends TypedIntlMessageGetter<object | undefined>>(message: T, values: Omit<FormatValuesFor<T>, DefaultValues>): JSX.Element;
+    format(message: any): JSX.Element;
+}

package/dist/react.js

@@ -0,0 +1,80 @@
+"use strict";
+var __extends = (this && this.__extends) || (function () {
+    var extendStatics = function (d, b) {
+        extendStatics = Object.setPrototypeOf ||
+            ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
+            function (d, b) { for (var p in b) if (Object.prototype.hasOwnProperty.call(b, p)) d[p] = b[p]; };
+        return extendStatics(d, b);
+    };
+    return function (d, b) {
+        if (typeof b !== "function" && b !== null)
+            throw new TypeError("Class extends value " + String(b) + " is not a constructor or null");
+        extendStatics(d, b);
+        function __() { this.constructor = d; }
+        d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
+    };
+})();
+var __read = (this && this.__read) || function (o, n) {
+    var m = typeof Symbol === "function" && o[Symbol.iterator];
+    if (!m) return o;
+    var i = m.call(o), r, ar = [], e;
+    try {
+        while ((n === void 0 || n-- > 0) && !(r = i.next()).done) ar.push(r.value);
+    }
+    catch (error) { e = { error: error }; }
+    finally {
+        try {
+            if (r && !r.done && (m = i["return"])) m.call(i);
+        }
+        finally { if (e) throw e.error; }
+    }
+    return ar;
+};
+var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IntlManagerReact = void 0;
+var React = require("react");
+var intl_manager_1 = require("./intl-manager");
+var IntlManagerReact = /** @class */ (function (_super) {
+    __extends(IntlManagerReact, _super);
+    function IntlManagerReact() {
+        var _this = _super.apply(this, __spreadArray([], __read(arguments), false)) || this;
+        /**
+         * A reactive component form of `intl.format` that automatically updates when
+         * the application's locale changes and when new data is loaded for the
+         * subject message.
+         */
+        _this.IntlMessage = function (props) {
+            var message = props.message, values = props.values;
+            // Use the locale from this point in the application, which may be
+            // different from the global locale.
+            var locale = React.useSyncExternalStore(_this.onLocaleChange, function () { return _this.currentLocale; });
+            // Source the actual message to render for that locale from its loader.
+            // TODO(faulty): This can and should be replaced by a
+            // `use(messagesLoadedPromise)` once `use` is shipped to stable.
+            React.useSyncExternalStore(message.onChange, function () { return message(locale); });
+            // The return the formatted version of that string.
+            if (typeof message === 'string')
+                return message;
+            return React.createElement(React.Fragment, undefined, _this.formatToParts(message, values));
+        };
+        return _this;
+    }
+    IntlManagerReact.prototype.format = function (message, values) {
+        // A string literal means there's no locale dependency, so it can just be
+        // formatted directly without any subscription.
+        if (typeof message === 'string')
+            return this.formatToParts(message);
+        return React.createElement(this.IntlMessage, { message: message, values: values });
+    };
+    return IntlManagerReact;
+}(intl_manager_1.IntlManager));
+exports.IntlManagerReact = IntlManagerReact;

package/dist/types.d.ts

@@ -0,0 +1,158 @@
+import type { InternalIntlMessage } from './message';
+import type { IntlMessageGetterAdditions } from './message-loader';
+/**
+ * Use this function to define messages as part of the `@discord/intl`
+ * system, with type checking support.
+ *
+ * This function does not actually exist, and gets compiled out as part
+ * of the bundling process both on web and mobile. See the
+ * `@discord/intl/README.md` for more information.
+ */
+export declare function defineMessages(messages: object): object;
+
+/**
+ * A map of tag names to render functions to apply when the tags are
+ * encountered while formatting a message. Each `IntlManager` can be
+ * constructed with a different map of these elements, for example to allow
+ * one manager to render React output while another renders accessibility text.
+ */
+export type RichTextElementMap = Record<string, (chunks: any[]) => any>;
+
+/**
+ * Messages with no rich formatting and no value interpolations are just plain
+ * strings, and are able to skip multiple formatting steps to work more
+ * efficiently. This type represents those messages distinctly.
+ */
+type PlainIntlMessage = string;
+/**
+ * A richly-formatted message that injects dynamic values while formatting,
+ * with the types of those values defined by the `FormatValues` object. All
+ * messages of this type must have at least one value in the object, otherwise
+ * the message should be typed as a `PlainIntlMessage`.
+ */
+type TypedIntlMessage<FormatValues extends object> = InternalIntlMessage & {
+  values: FormatValues;
+};
+
+type AnyIntlMessage<FormatValues extends object | undefined = undefined> =
+  FormatValues extends object ? TypedIntlMessage<FormatValues> : PlainIntlMessage;
+
+/**
+ * Getter function that retrieves a message that best matches the requested
+ * locale. `FormatValues` represents either an object containing all of the
+ * value types that are required to format the message, or `undefined` to
+ * represent that there are no values required and the message is a plain
+ * string.
+ */
+export type TypedIntlMessageGetter<FormatValues extends object | undefined> =
+  IntlMessageGetterAdditions & {
+    (locale: string): AnyIntlMessage<FormatValues>;
+  };
+
+/**
+ * Common utility type for converting a union type to an intersection of all
+ * the types in that union.
+ */
+type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void
+  ? I
+  : never;
+
+/**
+ * Given a message getter of type `T` (which may be a union of multiple message
+ * types), return a combined type representing the intersection of all values
+ * needed to satisfy the mix of values.
+ *
+ * For example, given a variable representing one of two message getters, where
+ * one requires a single value to be formatted, but the other requires an
+ * additional value on top of that one:
+ *
+ * ```typescript
+ * // message1: "Hello {username}"
+ * // message2: "Hello {username}, it's {currentDate, date}"
+ * const message = someCondition ? message1 || message2;
+ * ```
+ *
+ * Attempting to format this message would require that both `username` _and_
+ * `currentDate` are supplied, so that all possible cases are covered, which is
+ * what this type resolves:
+ *
+ * ```typescript
+ * type ResolvedValuesTypes = FormatValuesFor<typeof message>;
+ * // => {username: string, currentDate: Date}
+ * ```
+ *
+ * This values type can then be used to enforce that all values are passed to
+ * functions that format the message, like `i18n.format`:
+ *
+ * ```typescript
+ * declare function format<T>(message: T, values: FormatValuesFor<T>): string;
+ * ```
+ *
+ * ## Mixed message types
+ *
+ * If T is a union of message types including both rich messages requiring
+ * values _and_ plain string messages with no values, this type will still
+ * properly resolve all of the required values, assuming that the getters for
+ * the plain messages use the convention of passing `undefined` as the generic
+ * argument, representing "no values should be passed for this message".
+ *
+ *
+ * ## Why this type?
+ *
+ * All "messages" are really defined as functions that return a specific
+ * value of the message for a requested locale, `(locale: string) => Message`.
+ * This is named `TypedIntlMessageGetter<T>`, where `T` is the definition of
+ * the values required to format the message.
+ *
+ * This type requires being passed the entire getter function rather than the
+ * returned message types, as narrowing to the returned type prevents
+ * TypeScript from distributing the union properly. This surfaces as error
+ * messages showing up on the _message_ type rather than the _value_ type when
+ * they don't match, which doesn't give the user any helpful information about
+ * what's wrong. This method ensures the value type is always the one being
+ * checked against the provided message types, and error messages will be
+ * accurate as a result.
+ */
+type FormatValuesFor<T> =
+  // `[]` syntax forces TypeScript to not distribute the possible union of
+  // types, meaning this represents "_all_ values of T are an extension of
+  // the parent type", which in this case represents messages with no
+  // format values. If that condition is matched, then `FormatValues` _cannot_
+  // be supplied, represented by the `never`. This prevents accidentally
+  // passing an object, even an empty one, for those strings, and allows the
+  // formatter to optimize a little more on each call.
+  [T] extends [TypedIntlMessageGetter<undefined>]
+    ? never
+    : // The `never` conditino needs to be repeated here, but this time _without_
+      // the `[]` syntax, so that only the union elements with actual values are
+      // included in the union. Without this, the `infer U` on the latter side
+      // fails to resolve and the type just becomes `never`.
+      UnionToIntersection<
+        T extends TypedIntlMessageGetter<undefined>
+          ? never
+          : T extends TypedIntlMessageGetter<infer U>
+            ? U
+            : never
+      >;
+
+/**
+ * A generic definition of a `format*` function that accepts any message
+ * argument as the first parameter, and the required values object for that
+ * message as the second parameter. The second parameter
+ *
+ * An optional third parameter for additional options can be specified as the
+ * second generic type parameter.
+ */
+export interface IntlFormatFn<
+  T extends object | undefined,
+  DefaultValues extends string | number | symbol,
+  OptionsType,
+  ResultType,
+> {
+  (message: TypedIntlMessageGetter<T>, options?: OptionsType): ResultType;
+  (
+    message: TypedIntlMessageGetter<T>,
+    values: Omit<FormatValuesFor<T>, DefaultValues>,
+    options?: OptionsType,
+  ): ResultType;
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@discord/intl",
+  "version": "0.0.1",
+  "license": "MIT",
+  "description": "Client runtime for managing messages and translations in a React project.",
+  "main": "./src/index.ts",
+  "exports": {
+    ".": {
+      "default": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@formatjs/icu-messageformat-parser": "^2.7.6",
+    "@formatjs/intl": "^2.10.1",
+    "intl-messageformat": "^10.5.11"
+  },
+  "devDependencies": {
+    "@swc/cli": "^0.3.12",
+    "@swc/core": "^1.4.11",
+    "typescript": "*"
+  },
+  "peerDependencies": {
+    "@rspack/core": "0.x || 1.x",
+    "webpack": "^5.0.0",
+    "react": "> 16"
+  },
+  "peerDependenciesMeta": {
+    "@rspack/core": {
+      "optional": true
+    },
+    "webpack": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsc && cp -r ./src/*.d.ts dist/"
+  }
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export { IntlManager, createLoader, DEFAULT_LOCALE } from './intl-manager';
+export { IntlManagerReact } from './react';
+
+export type * from './types.d.ts';

package/src/intl-manager.ts

@@ -0,0 +1,166 @@
+import { IntlShape, createIntl } from '@formatjs/intl';
+import {
+  PART_TYPE as FormatPartType,
+  Formats,
+  Formatters,
+  IntlMessageFormat,
+} from 'intl-messageformat';
+
+import { LocaleImportMap, MessageLoader } from './message-loader';
+
+import type { TypedIntlMessageGetter, FormatValuesFor, RichTextElementMap } from './types';
+
+/**
+ * Fallback locale used for all internationalization when an operation in the
+ * requested locale is not possible.
+ */
+export const DEFAULT_LOCALE: string = 'en-US';
+
+export class IntlManager<
+  DefaultElements extends RichTextElementMap,
+  DefaultValues extends keyof DefaultElements,
+> {
+  defaultLocale: string;
+  currentLocale: string;
+  intl: IntlShape;
+
+  /**
+   * When formatting tag elements like `<b>value</b>`, these functions will
+   * automatically be used by all messages, unless they are explicitly removed
+   * for a specific call, either by overriding the value or by calling a
+   * dedicated method like `formatToPlainString` which will remove all
+   * rich elements from the string and return only the plain text result.
+   */
+  defaultRichTextElements: DefaultElements;
+
+  _localeSubscriptions: Set<(locale: string) => void>;
+
+  constructor(defaultLocale: string = DEFAULT_LOCALE, defaultRichTextElements: DefaultElements) {
+    this.defaultLocale = defaultLocale;
+    this.currentLocale = defaultLocale;
+    this.intl = createIntl({
+      formats: IntlMessageFormat.formats,
+      defaultLocale,
+      locale: defaultLocale,
+    });
+
+    this.defaultRichTextElements = defaultRichTextElements;
+    this._localeSubscriptions = new Set();
+  }
+
+  /**
+   * Set the locale for this package to use. This is a global change, and all
+   * methods on this object will use this locale for formatting.
+   */
+  setLocale(locale: string) {
+    this.currentLocale = locale;
+    this.intl = createIntl({ defaultLocale: this.defaultLocale, locale });
+    this.emitLocaleChange(locale);
+  }
+
+  emitLocaleChange(locale: string) {
+    for (const callback of this._localeSubscriptions) {
+      callback(locale);
+    }
+  }
+
+  /**
+   * Subscribe to changes in the current locale for this manager.
+   */
+  onLocaleChange = (callback: (locale: string) => void) => {
+    this._localeSubscriptions.add(callback);
+    return () => this._localeSubscriptions.delete(callback);
+  };
+
+  /**
+   * Format the given message in the current locale with the provided values.
+   * The returned values is _always_ an Array of parts, even if the message is
+   * a simple string value.
+   *
+   * This function is the basis of how messages are normally formatted, and can
+   * be used anywhere. However, it is not reactive and only functions on the
+   * data that is currently loaded and known. For a reactive function that
+   * automatically updates when the locale changes or when new data is loaded,
+   * use `format`, which will wrap the formatting in a React component that
+   * subscribes to the current locale and state of loaded messages.
+   */
+  formatToParts<T extends TypedIntlMessageGetter<object | undefined>>(
+    message: T,
+  ): Array<string | any>;
+  formatToParts<T extends TypedIntlMessageGetter<object | undefined>>(
+    message: T,
+    values: Omit<FormatValuesFor<T>, DefaultValues>,
+  ): Array<string | any>;
+  formatToParts<T extends TypedIntlMessageGetter<object | undefined>>(
+    message: T,
+    values?: Omit<FormatValuesFor<T>, DefaultValues>,
+  ) {
+    if (typeof message === 'string') return [message];
+    const resolvedMessage = typeof message === 'function' ? message(this.currentLocale) : message;
+    if (typeof resolvedMessage === 'string') return [resolvedMessage];
+
+    const resolvedValues =
+      values != null
+        ? { ...this.defaultRichTextElements, ...values }
+        : this.defaultRichTextElements;
+    const parts = resolvedMessage.formatToParts(
+      this.intl.formatters as Formatters,
+      this.intl.formats as Formats,
+      resolvedValues,
+    );
+
+    const result = [];
+    let inLiteral = false;
+    for (const part of parts) {
+      // This condition merges consecutive literal elements (static strings)
+      // into single parts to reduce the number of nodes in the result. This
+      // condition will never be true on the first loop, ensuring that the
+      // array must at least have one entry before it attempts to concatenate
+      // onto that value again.
+      if (inLiteral && (inLiteral = part.type === FormatPartType.literal)) {
+        result[result.length - 1] += part.value;
+        continue;
+      }
+
+      inLiteral = part.type === FormatPartType.literal;
+      result.push(part.value);
+    }
+
+    return result;
+  }
+
+  /**
+   * Format the given message with the provided values, removing any styling
+   * and non-textual content from the message, returning a plain string.
+   */
+  formatToPlainString<T extends TypedIntlMessageGetter<object | undefined>>(message: T): string;
+  formatToPlainString<T extends TypedIntlMessageGetter<object | undefined>>(
+    message: T,
+    values: Omit<FormatValuesFor<T>, DefaultValues>,
+  ): string;
+  formatToPlainString<T extends TypedIntlMessageGetter<object | undefined>>(
+    message: T,
+    values?: Omit<FormatValuesFor<T>, DefaultValues>,
+  ) {
+    if (typeof message === 'string') return message;
+    const resolvedMessage = message(this.currentLocale);
+    if (typeof resolvedMessage === 'string') return resolvedMessage;
+
+    // No need to pass in `defaultRichTextElements`, since the stylistic tags
+    // will be removed from the string anyway.
+    return resolvedMessage.formatToPlainString(
+      this.intl.formatters as Formatters,
+      this.intl.formats as Formats,
+      values,
+    );
+  }
+}
+
+/**
+ * Create a new MessageLoader, which handles lazily loading messages for
+ * different locales and sanity checks as needed to provide accessors for each
+ * message defined in `messageKeys`.
+ */
+export function createLoader(messageKeys: string[], localeImportMap: LocaleImportMap) {
+  return new MessageLoader(messageKeys, localeImportMap);
+}