@lingui/macro 3.11.1 → 3.13.1

package/constants.js

@@ -3,7 +3,7 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.EXTRACT_MARK = exports.COMMENT = exports.MESSAGE = exports.ID = void 0;
+exports.CONTEXT = exports.EXTRACT_MARK = exports.COMMENT = exports.MESSAGE = exports.ID = void 0;
 var ID = "id";
 exports.ID = ID;
 var MESSAGE = "message";
@@ -11,4 +11,6 @@ exports.MESSAGE = MESSAGE;
 var COMMENT = "comment";
 exports.COMMENT = COMMENT;
 var EXTRACT_MARK = "i18n";
-exports.EXTRACT_MARK = EXTRACT_MARK;
+exports.EXTRACT_MARK = EXTRACT_MARK;
+var CONTEXT = "context";
+exports.CONTEXT = CONTEXT;

package/global.d.ts

@@ -1,16 +1,84 @@
-declare module '@lingui/macro' {
-  import type { MessageDescriptor } from "@lingui/core"
+// @ts-ignore
+declare module "@lingui/macro" {
+  import type { MessageDescriptor, I18n } from "@lingui/core"
 
   export type BasicType = {
     id?: string
     comment?: string
   }
 
+  /**
+   * Translates a message descriptor
+   *
+   * @example
+   * ```
+   * import { t } from "@lingui/macro";
+   * const message = t({
+   *   id: "msg.hello",
+   *   comment: "Greetings at the homepage",
+   *   message: `Hello ${name}`,
+   * });
+   * ```
+   *
+   * @example
+   * ```
+   * import { t } from "@lingui/macro";
+   * const message = t({
+   *   id: "msg.plural",
+   *   message: plural(value, { one: "...", other: "..." }),
+   * });
+   * ```
+   *
+   * @param descriptor The message descriptor to translate
+   */
+  export function t(descriptor: MessageDescriptor): string
+
+  /**
+   * Translates a template string using the global I18n instance
+   *
+   * @example
+   * ```
+   * import { t } from "@lingui/macro";
+   * const message = t`Hello ${name}`;
+   * ```
+   */
   export function t(
-    literals: TemplateStringsArray | MessageDescriptor,
+    literals: TemplateStringsArray,
     ...placeholders: any[]
   ): string
 
+  /**
+   * Translates a template string or message descriptor using a given I18n instance
+   *
+   * @example
+   * ```
+   * import { t } from "@lingui/macro";
+   * import { I18n } from "@lingui/core";
+   * const i18n = new I18n({
+   *   locale: "nl",
+   *   messages: { "Hello {0}": "Hallo {0}" },
+   * });
+   * const message = t(i18n)`Hello ${name}`;
+   * ```
+   *
+   * @example
+   * ```
+   * import { t } from "@lingui/macro";
+   * import { I18n } from "@lingui/core";
+   * const i18n = new I18n({
+   *   locale: "nl",
+   *   messages: { "Hello {0}": "Hallo {0}" },
+   * });
+   * const message = t(i18n)({ message: `Hello ${name}` });
+   * ```
+   */
+  export function t(
+    i18n: I18n
+  ): {
+    (literals: TemplateStringsArray, ...placeholders: any[]): string
+    (descriptor: MessageDescriptor): string
+  }
+
   export type UnderscoreDigit<T = string> = { [digit: string]: T }
   export type ChoiceOptions<T = string> = {
     offset?: number
@@ -21,20 +89,100 @@ declare module '@lingui/macro' {
     other?: T
   } & UnderscoreDigit<T>
 
-  export function plural(arg: number | string, options: ChoiceOptions & BasicType): string
+  /**
+   * Pluralize a message
+   *
+   * @example
+   * ```
+   * import { plural } from "@lingui/macro";
+   * const message = plural(count, {
+   *   one: "# Book",
+   *   other: "# Books",
+   * });
+   * ```
+   *
+   * @param value Determines the plural form
+   * @param options Object with available plural forms
+   */
+  export function plural(
+    value: number | string,
+    options: ChoiceOptions & BasicType
+  ): string
+
+  /**
+   * Pluralize a message using ordinal forms
+   *
+   * Similar to `plural` but instead of using cardinal plural forms,
+   * it uses ordinal forms.
+   *
+   * @example
+   * ```
+   * import { selectOrdinal } from "@lingui/macro";
+   * const message = selectOrdinal(count, {
+   *    one: "1st",
+   *    two: "2nd",
+   *    few: "3rd",
+   *    other: "#th",
+   * });
+   * ```
+   *
+   * @param value Determines the plural form
+   * @param options Object with available plural forms
+   */
   export function selectOrdinal(
-    arg: number | string,
+    value: number | string,
     options: ChoiceOptions & BasicType
   ): string
-  export function select(arg: string, choices: Record<string, string> & BasicType): string
-  export function defineMessages<M extends Record<string, MessageDescriptor>>(
-    messages: M
-  ): M
-  export function defineMessage(descriptor: MessageDescriptor): MessageDescriptor
+
+  /**
+   * Selects a translation based on a value
+   *
+   * Select works like a switch statement. It will
+   * select one of the forms in `options` object which
+   * key matches exactly `value`.
+   *
+   * @example
+   * ```
+   * import { select } from "@lingui/macro";
+   * const message = select(gender, {
+   *    male: "he",
+   *    female: "she",
+   *    other: "they",
+   * });
+   * ```
+   *
+   * @param value The key of choices to use
+   * @param choices
+   */
+  export function select(
+    value: string,
+    choices: Record<string, string> & BasicType
+  ): string
+
+  /**
+   * Define a message for later use
+   *
+   * `defineMessage` can be used to add comments for translators,
+   * or to override the message ID.
+   *
+   * @example
+   * ```
+   * import { defineMessage } from "@lingui/macro";
+   * const message = defineMessage({
+   *    comment: "Greetings on the welcome page",
+   *    message: `Welcome, ${name}!`,
+   * });
+   * ```
+   *
+   * @param descriptor The message descriptor
+   */
+  export function defineMessage(
+    descriptor: MessageDescriptor
+  ): MessageDescriptor
 
   export type ChoiceProps = {
     value?: string | number
-  }  & ChoiceOptions<string>
+  } & ChoiceOptions<string>
 
   /**
    * The types should be changed after this PR is merged
@@ -60,4 +208,4 @@ declare module '@lingui/macro' {
   export const Plural: any
   export const Select: any
   export const SelectOrdinal: any
-}
+}

package/index.d.ts

@@ -1,12 +1,7 @@
 import type { ReactElement, ComponentType, ReactNode } from "react"
-import type { MessageDescriptor } from "@lingui/core"
+import type { MessageDescriptor, I18n } from "@lingui/core"
 import type { TransRenderProps } from "@lingui/react"
 
-export function t(
-  literals: TemplateStringsArray | MessageDescriptor,
-  ...placeholders: any[]
-): string
-
 export type UnderscoreDigit<T = string> = { [digit: string]: T }
 export type ChoiceOptions<T = string> = {
   offset?: number
@@ -17,21 +12,166 @@ export type ChoiceOptions<T = string> = {
   other?: T
 } & UnderscoreDigit<T>
 
-export function plural(arg: number | string, options: ChoiceOptions): string
+/**
+ * Translates a message descriptor
+ *
+ * @example
+ * ```
+ * import { t } from "@lingui/macro";
+ * const message = t({
+ *   id: "msg.hello",
+ *   comment: "Greetings at the homepage",
+ *   message: `Hello ${name}`,
+ * });
+ * ```
+ *
+ * @example
+ * ```
+ * import { t } from "@lingui/macro";
+ * const message = t({
+ *   id: "msg.plural",
+ *   message: plural(value, { one: "...", other: "..." }),
+ * });
+ * ```
+ *
+ * @param descriptor The message descriptor to translate
+ */
+export function t(descriptor: MessageDescriptor): string
+
+/**
+ * Translates a template string using the global I18n instance
+ *
+ * @example
+ * ```
+ * import { t } from "@lingui/macro";
+ * const message = t`Hello ${name}`;
+ * ```
+ */
+export function t(
+  literals: TemplateStringsArray,
+  ...placeholders: any[]
+): string
+
+/**
+ * Translates a template string or message descriptor using a given I18n instance
+ *
+ * @example
+ * ```
+ * import { t } from "@lingui/macro";
+ * import { I18n } from "@lingui/core";
+ * const i18n = new I18n({
+ *   locale: "nl",
+ *   messages: { "Hello {0}": "Hallo {0}" },
+ * });
+ * const message = t(i18n)`Hello ${name}`;
+ * ```
+ *
+ * @example
+ * ```
+ * import { t } from "@lingui/macro";
+ * import { I18n } from "@lingui/core";
+ * const i18n = new I18n({
+ *   locale: "nl",
+ *   messages: { "Hello {0}": "Hallo {0}" },
+ * });
+ * const message = t(i18n)({ message: `Hello ${name}` });
+ * ```
+ */
+export function t(
+  i18n: I18n
+): {
+  (literals: TemplateStringsArray, ...placeholders: any[]): string
+  (descriptor: MessageDescriptor): string
+}
+
+/**
+ * Pluralize a message
+ *
+ * @example
+ * ```
+ * import { plural } from "@lingui/macro";
+ * const message = plural(count, {
+ *   one: "# Book",
+ *   other: "# Books",
+ * });
+ * ```
+ *
+ * @param value Determines the plural form
+ * @param options Object with available plural forms
+ */
+export function plural(value: number | string, options: ChoiceOptions): string
+
+/**
+ * Pluralize a message using ordinal forms
+ *
+ * Similar to `plural` but instead of using cardinal plural forms,
+ * it uses ordinal forms.
+ *
+ * @example
+ * ```
+ * import { selectOrdinal } from "@lingui/macro";
+ * const message = selectOrdinal(count, {
+ *    one: "1st",
+ *    two: "2nd",
+ *    few: "3rd",
+ *    other: "#th",
+ * });
+ * ```
+ *
+ * @param value Determines the plural form
+ * @param options Object with available plural forms
+ */
 export function selectOrdinal(
-  arg: number | string,
+  value: number | string,
   options: ChoiceOptions
 ): string
-export function select(arg: string, choices: Record<string, string>): string
-export function defineMessages<M extends Record<string, MessageDescriptor>>(
-  messages: M
-): M
+
+/**
+ * Selects a translation based on a value
+ *
+ * Select works like a switch statement. It will
+ * select one of the forms in `options` object which
+ * key matches exactly `value`.
+ *
+ * @example
+ * ```
+ * import { select } from "@lingui/macro";
+ * const message = select(gender, {
+ *    male: "he",
+ *    female: "she",
+ *    other: "they",
+ * });
+ * ```
+ *
+ * @param value The key of choices to use
+ * @param choices
+ */
+export function select(value: string, choices: ChoiceOptions): string
+
+/**
+ * Define a message for later use
+ *
+ * `defineMessage` can be used to add comments for translators,
+ * or to override the message ID.
+ *
+ * @example
+ * ```
+ * import { defineMessage } from "@lingui/macro";
+ * const message = defineMessage({
+ *    comment: "Greetings on the welcome page",
+ *    message: `Welcome, ${name}!`,
+ * });
+ * ```
+ *
+ * @param descriptor The message descriptor
+ */
 export function defineMessage(descriptor: MessageDescriptor): MessageDescriptor
 
 export type TransProps = {
   id?: string
   comment?: string
   values?: Record<string, unknown>
+  context?: string
   component?: React.ComponentType<TransRenderProps>
   render?: (props: TransRenderProps) => ReactElement<any, any> | null
 }

package/index.js

@@ -55,6 +55,7 @@ function macro(_ref) {
       babel = _ref.babel;
   var jsxNodes = [];
   var jsNodes = [];
+  var needsI18nImport = false;
   Object.keys(references).forEach(function (tagName) {
     var nodes = references[tagName];
     var macroType = getMacroType(tagName);
@@ -79,7 +80,7 @@ function macro(_ref) {
     var macro = new _macroJs.default(babel, {
       i18nImportName: i18nImportName
     });
-    macro.replacePath(path);
+    if (macro.replacePath(path)) needsI18nImport = true;
   });
   jsxNodes.filter(isRootPath(jsxNodes)).forEach(function (path) {
     if (alreadyVisited(path)) return;
@@ -87,7 +88,7 @@ function macro(_ref) {
     macro.replacePath(path);
   });
 
-  if (jsNodes.length) {
+  if (needsI18nImport) {
     addImport(babel, state, i18nImportModule, i18nImportName);
   }
 
@@ -146,7 +147,6 @@ function alreadyVisited(path) {
 
 function getMacroType(tagName) {
   switch (tagName) {
-    case "defineMessages":
     case "defineMessage":
     case "arg":
     case "t":

package/macroJs.js

@@ -53,7 +53,7 @@ var MacroJs = /*#__PURE__*/function () {
     (0, _defineProperty2.default)(this, "types", void 0);
     (0, _defineProperty2.default)(this, "i18nImportName", void 0);
     (0, _defineProperty2.default)(this, "_expressionIndex", void 0);
-    (0, _defineProperty2.default)(this, "replacePathWithMessage", function (path, _ref3) {
+    (0, _defineProperty2.default)(this, "replacePathWithMessage", function (path, _ref3, linguiInstance) {
       var id = _ref3.id,
           message = _ref3.message,
           values = _ref3.values,
@@ -87,7 +87,7 @@ var MacroJs = /*#__PURE__*/function () {
         args.push(_this.types.objectExpression(options));
       }
 
-      var newNode = _this.types.callExpression(_this.types.memberExpression(_this.types.identifier(_this.i18nImportName), _this.types.identifier("_")), args); // preserve line number
+      var newNode = _this.types.callExpression(_this.types.memberExpression(linguiInstance !== null && linguiInstance !== void 0 ? linguiInstance : _this.types.identifier(_this.i18nImportName), _this.types.identifier("_")), args); // preserve line number
 
 
       newNode.loc = path.node.loc;
@@ -102,24 +102,60 @@ var MacroJs = /*#__PURE__*/function () {
       if (_this.isDefineMessage(path.node)) {
         _this.replaceDefineMessage(path);
 
-        return;
+        return true;
+      } // t(i18nInstance)`Message` -> i18nInstance._('Message')
+
+
+      if (_this.types.isCallExpression(path.node) && _this.types.isTaggedTemplateExpression(path.parentPath.node) && _this.types.isIdentifier(path.node.arguments[0]) && _this.isIdentifier(path.node.callee, "t")) {
+        // Use the first argument as i18n instance instead of the default i18n instance
+        var i18nInstance = path.node.arguments[0];
+
+        var _tokens = _this.tokenizeNode(path.parentPath.node);
+
+        var _messageFormat = new _icu.default();
+
+        var _messageFormat$fromTo = _messageFormat.fromTokens(_tokens),
+            _messageRaw = _messageFormat$fromTo.message,
+            _values = _messageFormat$fromTo.values,
+            _id = _messageFormat$fromTo.id,
+            _comment = _messageFormat$fromTo.comment;
+
+        var _message = normalizeWhitespace(_messageRaw);
+
+        _this.replacePathWithMessage(path.parentPath, {
+          id: _id,
+          message: _message,
+          values: _values,
+          comment: _comment
+        }, i18nInstance);
+
+        return false;
+      } // t(i18nInstance)(messageDescriptor) -> i18nInstance._(messageDescriptor)
+
+
+      if (_this.types.isCallExpression(path.node) && _this.types.isCallExpression(path.parentPath.node) && _this.types.isIdentifier(path.node.arguments[0]) && _this.isIdentifier(path.node.callee, "t")) {
+        var _i18nInstance = path.node.arguments[0];
+
+        _this.replaceTAsFunction(path.parentPath, _i18nInstance);
+
+        return false;
       }
 
       if (_this.types.isCallExpression(path.node) && _this.isIdentifier(path.node.callee, "t")) {
         _this.replaceTAsFunction(path);
 
-        return;
+        return true;
       }
 
       var tokens = _this.tokenizeNode(path.node);
 
       var messageFormat = new _icu.default();
 
-      var _messageFormat$fromTo = messageFormat.fromTokens(tokens),
-          messageRaw = _messageFormat$fromTo.message,
-          values = _messageFormat$fromTo.values,
-          id = _messageFormat$fromTo.id,
-          comment = _messageFormat$fromTo.comment;
+      var _messageFormat$fromTo2 = messageFormat.fromTokens(tokens),
+          messageRaw = _messageFormat$fromTo2.message,
+          values = _messageFormat$fromTo2.values,
+          id = _messageFormat$fromTo2.id,
+          comment = _messageFormat$fromTo2.comment;
 
       var message = normalizeWhitespace(messageRaw);
 
@@ -129,6 +165,8 @@ var MacroJs = /*#__PURE__*/function () {
         values: values,
         comment: comment
       });
+
+      return true;
     });
     (0, _defineProperty2.default)(this, "replaceDefineMessage", function (path) {
       // reset the expression counter
@@ -138,10 +176,10 @@ var MacroJs = /*#__PURE__*/function () {
 
       path.replaceWith(descriptor);
     });
-    (0, _defineProperty2.default)(this, "replaceTAsFunction", function (path) {
+    (0, _defineProperty2.default)(this, "replaceTAsFunction", function (path, linguiInstance) {
       var descriptor = _this.processDescriptor(path.node.arguments[0]);
 
-      var newNode = _this.types.callExpression(_this.types.memberExpression(_this.types.identifier(_this.i18nImportName), _this.types.identifier("_")), [descriptor]);
+      var newNode = _this.types.callExpression(_this.types.memberExpression(linguiInstance !== null && linguiInstance !== void 0 ? linguiInstance : _this.types.identifier(_this.i18nImportName), _this.types.identifier("_")), [descriptor]);
 
       path.replaceWith(newNode);
     });
@@ -166,9 +204,9 @@ var MacroJs = /*#__PURE__*/function () {
       if (tokens != null) {
         var messageFormat = new _icu.default();
 
-        var _messageFormat$fromTo2 = messageFormat.fromTokens(tokens),
-            messageRaw = _messageFormat$fromTo2.message,
-            values = _messageFormat$fromTo2.values;
+        var _messageFormat$fromTo3 = messageFormat.fromTokens(tokens),
+            messageRaw = _messageFormat$fromTo3.message,
+            values = _messageFormat$fromTo3.values;
 
         var message = normalizeWhitespace(messageRaw);
         messageNode = _this.types.stringLiteral(message);

package/macroJsx.js

@@ -81,7 +81,8 @@ var MacroJSX = /*#__PURE__*/function () {
       var _this$stripMacroAttri = _this.stripMacroAttributes(path.node),
           attributes = _this$stripMacroAttri.attributes,
           id = _this$stripMacroAttri.id,
-          comment = _this$stripMacroAttri.comment;
+          comment = _this$stripMacroAttri.comment,
+          context = _this$stripMacroAttri.context;
 
       if (!id && !message) {
         return;
@@ -103,6 +104,10 @@ var MacroJSX = /*#__PURE__*/function () {
         if (comment) {
           attributes.push(_this.types.jsxAttribute(_this.types.jsxIdentifier(_constants.COMMENT), _this.types.stringLiteral(comment)));
         }
+      }
+
+      if (context) {
+        attributes.push(_this.types.jsxAttribute(_this.types.jsxIdentifier(_constants.CONTEXT), _this.types.stringLiteral(context)));
       } // Parameters for variable substitution
 
 
@@ -147,7 +152,8 @@ var MacroJSX = /*#__PURE__*/function () {
       var id = attributes.filter(_this.attrName([_constants.ID]))[0];
       var message = attributes.filter(_this.attrName([_constants.MESSAGE]))[0];
       var comment = attributes.filter(_this.attrName([_constants.COMMENT]))[0];
-      var reserved = [_constants.ID, _constants.MESSAGE, _constants.COMMENT];
+      var context = attributes.filter(_this.attrName([_constants.CONTEXT]))[0];
+      var reserved = [_constants.ID, _constants.MESSAGE, _constants.COMMENT, _constants.CONTEXT];
 
       if (_this.isI18nComponent(node)) {// no reserved prop names
       } else if (_this.isChoiceComponent(node)) {
@@ -158,6 +164,7 @@ var MacroJSX = /*#__PURE__*/function () {
         id: maybeNodeValue(id),
         message: maybeNodeValue(message),
         comment: maybeNodeValue(comment),
+        context: maybeNodeValue(context),
         attributes: attributes.filter(_this.attrName(reserved, true))
       };
     });
@@ -225,7 +232,7 @@ var MacroJSX = /*#__PURE__*/function () {
     (0, _defineProperty2.default)(this, "tokenizeChoiceComponent", function (node) {
       var element = node.openingElement;
       var format = element.name.name.toLowerCase();
-      var props = element.attributes.filter(_this.attrName([_constants.ID, _constants.COMMENT, _constants.MESSAGE, "key", // we remove <Trans /> react props that are not useful for translation
+      var props = element.attributes.filter(_this.attrName([_constants.ID, _constants.COMMENT, _constants.MESSAGE, _constants.CONTEXT, "key", // we remove <Trans /> react props that are not useful for translation
       "render", "component", "components"], true));
       var token = {
         type: "arg",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lingui/macro",
-  "version": "3.11.1",
+  "version": "3.13.1",
   "description": "Macro for generating messages in ICU MessageFormat syntax",
   "main": "index.js",
   "author": {
@@ -30,10 +30,12 @@
   ],
   "dependencies": {
     "@babel/runtime": "^7.11.2",
-    "@lingui/conf": "^3.11.1",
+    "@lingui/conf": "^3.13.1",
     "ramda": "^0.27.1"
   },
   "peerDependencies": {
+    "@lingui/core": "^3.13.0",
+    "@lingui/react": "^3.13.0",
     "babel-plugin-macros": "2 || 3"
   }
 }