@lingui/macro 3.10.1 → 3.12.0

package/global.d.ts

@@ -1,13 +1,68 @@
-declare module '@lingui/macro' {
-  import type { MessageDescriptor } from "@lingui/core"
+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 messageDescriptior The descriptor to translate
+   */
+  export function t(messageDescriptior: 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 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}`;
+   * ```
+   */
   export function t(
-    literals: TemplateStringsArray | MessageDescriptor,
+    i18n: I18n,
+    literals: TemplateStringsArray,
     ...placeholders: any[]
   ): string
 
@@ -21,20 +76,107 @@ 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
+
+  /**
+   * 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
+
+  /**
+   * Defines multiple messages for extraction
+   */
   export function defineMessages<M extends Record<string, MessageDescriptor>>(
     messages: M
   ): M
-  export function defineMessage(descriptor: MessageDescriptor): MessageDescriptor
+
+  /**
+   * 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 +202,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,15 +12,156 @@ 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 messageDescriptior The descriptor to translate
+ */
+export function t(messageDescriptior: 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 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}`;
+ * ```
+ */
+export function t(
+  i18n: I18n,
+  literals: TemplateStringsArray,
+  ...placeholders: any[]
+): 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
+
+/**
+ * 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
+
+/**
+ * Defines multiple messages for extraction
+ *
+ * @see {@link defineMessage} for more details
+ */
 export function defineMessages<M extends Record<string, MessageDescriptor>>(
   messages: M
 ): M
+
+/**
+ * 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 = {

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);
   }
 

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,51 @@ 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;
       }
 
       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 +156,8 @@ var MacroJs = /*#__PURE__*/function () {
         values: values,
         comment: comment
       });
+
+      return true;
     });
     (0, _defineProperty2.default)(this, "replaceDefineMessage", function (path) {
       // reset the expression counter
@@ -166,9 +195,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);
@@ -210,7 +239,9 @@ var MacroJs = /*#__PURE__*/function () {
         quasis: R.map(function (text) {
           // Don't output tokens without text.
           // if it's an unicode we keep the cooked value because it's the parsed value by babel (without unicode chars)
-          var value = /\\u[a-fA-F0-9]{4}/g.test(text.value.raw) ? text.value.cooked : text.value.raw;
+          // This regex will detect if a string contains unicode chars, when they're we should interpolate them
+          // why? because platforms like react native doesn't parse them, just doing a JSON.parse makes them UTF-8 friendly
+          var value = /\\u[a-fA-F0-9]{4}|\\x[a-fA-F0-9]{2}/g.test(text.value.raw) ? text.value.cooked : text.value.raw;
           if (value === "") return null;
           return {
             type: "text",

package/macroJsx.js

@@ -193,8 +193,10 @@ var MacroJSX = /*#__PURE__*/function () {
           var tokenize = R.pipe( // Don"t output tokens without text.
           R.evolve({
             quasis: R.map(function (text) {
-              // Don"t output tokens without text.
-              var value = /\\u[a-fA-F0-9]{4}/g.test(text.value.raw) ? text.value.cooked : text.value.raw;
+              // if it's an unicode we keep the cooked value because it's the parsed value by babel (without unicode chars)
+              // This regex will detect if a string contains unicode chars, when they're we should interpolate them
+              // why? because platforms like react native doesn't parse them, just doing a JSON.parse makes them UTF-8 friendly
+              var value = /\\u[a-fA-F0-9]{4}|\\x[a-fA-F0-9]{2}/g.test(text.value.raw) ? text.value.cooked : text.value.raw;
               if (value === "") return null;
               return _this.tokenizeText(_this.clearBackslashes(value));
             }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lingui/macro",
-  "version": "3.10.1",
+  "version": "3.12.0",
   "description": "Macro for generating messages in ICU MessageFormat syntax",
   "main": "index.js",
   "author": {
@@ -30,7 +30,7 @@
   ],
   "dependencies": {
     "@babel/runtime": "^7.11.2",
-    "@lingui/conf": "^3.10.1",
+    "@lingui/conf": "^3.12.0",
     "ramda": "^0.27.1"
   },
   "peerDependencies": {