improvement: Context

docs/ref/catalog-formats.rst

@@ -26,6 +26,7 @@ The advantages of this format are:
 
    #: src/App.js:3
    #  Comment for translators
+   msgctx "context"
    msgid "messageId"
    msgstr "Translated Message"
 
@@ -79,9 +80,9 @@ With `po-gettext`, plural messages are exported in the following way, depending
 Note that this format comes with several caveats and should therefore only be used if using ICU plurals in PO files is
 not an option:
 
-  - Nested/multiple plurals in one message as shown in :jsmacro:`plural` are not supported as they cannot be expressed 
+  - Nested/multiple plurals in one message as shown in :jsmacro:`plural` are not supported as they cannot be expressed
     with gettext plurals. Messages containing nested/multiple formats will not be output correctly.
-  
+
   - :jsmacro:`select` and :jsmacro:`selectOrdinal` cannot be expressed with gettext plurals, but the original ICU format
     is still saved to the `msgid`/`msgstr` properties. To disable the warning that this might not be the expected
     behavior, include :code:`{ disableSelectWarning: true }` in the :conf:`formatOptions`.
@@ -123,6 +124,7 @@ process catalog data.
       "messageId": {
          "translation": "Translated message",
          "defaults": "Default message",
+         "context": "more context",
          "description": "Comment for translators",
          "origin": [["src/App.js", 3]]
       },

docs/ref/macro.rst

@@ -213,11 +213,12 @@ into a *Message Descriptor* wrapped inside of ``i18n._`` call.
       message?: String,
       values?: Object,
       formats?: Object,
-      comment?: string
+      comment?: string,
+      context?: string
    }
 
-``id`` is message ID and the only required parameter. ``id`` and ``message``
-are extracted to message catalog. Only ``id``, ``values``, and ``formats``
+``id`` is message ID and the only required parameter. ``id``, ``message``, ``comment``
+and ``context`` are extracted to message catalog. Only ``id``, ``context``, ``values``, and ``formats``
 are used at runtime, all other attributes are removed from production code
 for size optimization.
 
@@ -340,6 +341,40 @@ as if it were wrapped in ``t`` macro. ``message`` also accepts any other macros:
       values: { value }
    })
 
+You can also use ``context`` to have different entries in catalog for
+identical messages and allow translator to provide differents translations:
+
+.. code-block:: jsx
+
+   import { t } from "@lingui/macro"
+   const message = t({
+      comment: 'Commercial term for Free offer',
+      context: 'commercial subapp',
+      message: 'Free'
+   })
+
+   const anotherMessage = t({
+      comment: 'Like in "free to move the item"',
+      context: 'main subapp',
+      message: 'Free'
+   })
+
+   // ↓ ↓ ↓ ↓ ↓ ↓
+
+   import { i18n } from "@lingui/core"
+   const message = i18n._(/*i18n*/{
+      comment: 'Commercial term for Free offer',
+      context: 'commercial subapp',
+      message: 'Free'
+   })
+
+   const anotherMessage = i18n._(/*i18n*/{
+      comment: 'Like in "free to move the item"',
+      context: 'main subapp',
+      message: 'Free'
+   })
+
+
 plural
 ^^^^^^
 
@@ -437,8 +472,21 @@ two counters:
 
 .. important::
 
-   Use ``plural`` inside :jsmacro:`t` macro if you want to add custom ``id``
-   or ``comment`` for translators.
+   Use ``plural`` inside :jsmacro:`t` macro if you want to add custom ``id``, ``comment``
+   or ``context`` for translators.
+
+.. code-block:: jsx
+
+   import { t } from "@lingui/macro"
+   const message = t({
+      comment: 'Purchase summary',
+      context: 'cart',
+      message: plural(count, {
+         one: "# article",
+         other: "# articles"
+      })
+   })
+
 
 selectOrdinal
 ^^^^^^^^^^^^^
@@ -527,6 +575,7 @@ Unlike the other JS macros, it doesn't wrap generated *MessageDescription* into
    type MessageDescriptor = {
      id?: string,
      message?: string,
+     context?: string,
      comment?: string
    }
 
@@ -576,7 +625,7 @@ string literals don't need to be tagged with :jsmacro:`t`.
    }
 
 ``comment`` is a comment for translators. It's extracted to the message catalog
-and it gives extra context for translators. It's removed from production code:
+and it gives extra context for translators. It is removed from production code:
 
 .. code-block:: jsx
 
@@ -611,7 +660,12 @@ and it gives extra context for translators. It's removed from production code:
 
       const message = "Navigation / About"
 
-   ``message`` and ``comment`` are used in message catalogs only.
+   ``message``, ``comment`` and are used in message catalogs only.
+
+``context`` is for both translators and developers. Unlike a comment, it creates
+a new entry in the catalog and allows to distinguish equal messages that would
+need different translation or to create subset of messages.
+It is also used in production code at runtime.
 
 JSX Macros
 ----------
@@ -644,6 +698,14 @@ comment
 Comment for translators to give them additional context about the message.
 It's removed from production code.
 
+context
+~~~~~~~~~~~
+
+Context is for both translators and developers. Unlike a comment, it creates
+a new entry in the catalog and allows to distinguish equal messages that would
+need different translation or to create subset of messages.
+It is also used in production code at runtime.
+
 render
 ~~~~~~
 
@@ -658,6 +720,7 @@ Trans
 
    :prop string id: Custom message ID
    :prop string comment: Comment for translators
+   :prop string context: Context to group messages or distinguish similar messages
 
 :jsxmacro:`Trans` is the basic macro for static messages, messages with variables,
 but also for messages with inline markup:

examples/create-react-app/package.json

@@ -3,8 +3,8 @@
   "version": "0.1.0",
   "private": true,
   "dependencies": {
-    "@lingui/react": "^3.13.2",
-    "@lingui/core": "^3.13.2",
+    "@lingui/react": "^3.14.1",
+    "@lingui/core": "^3.14.1",
     "react": "^17.0.1",
     "react-dom": "^17.0.1"
   },
@@ -42,8 +42,8 @@
     "@types/react-dom": "^16.9.9",
     "react-scripts": "4.0.0",
     "typescript": "^4.0.5",
-    "@lingui/cli": "^3.13.2",
-    "@lingui/loader": "^3.13.2",
-    "@lingui/macro": "^3.13.2"
+    "@lingui/cli": "^3.14.1",
+    "@lingui/loader": "^3.14.1",
+    "@lingui/macro": "^3.14.1"
   }
 }

examples/create-react-app/src/App.tsx

@@ -1,6 +1,6 @@
 import './App.css';
 import React, { useState } from 'react';
-import { Trans, Plural } from "@lingui/macro";
+import { Trans, Plural, t } from "@lingui/macro";
 import { i18n } from "@lingui/core";
 
 import { locales, dynamicActivate } from './i18n';
@@ -46,6 +46,9 @@ function App() {
           I have a balance of {i18n.number(1_000_000, { style: "currency", currency: "EUR" })}
           </Trans>
         </div>
+        <h3><Trans context="example ctxt">Context example:</Trans></h3>
+        <div>{t`Hello World`}</div>
+        <div>{t({context: 'example ctxt', message: 'Hello World'})}</div>
       </header>
     </div>
   );

examples/create-react-app/src/locales/cs/messages.po

@@ -19,6 +19,10 @@ msgstr "Příklad formátovače data:"
 msgid "Decrement"
 msgstr "Úbytek"
 
+#: src/App.tsx:51
+msgid "Hello World"
+msgstr "Ahoj Brno"
+
 #: src/App.tsx:45
 msgid "I have a balance of {0}"
 msgstr "Mám zůstatek {0}"
@@ -43,6 +47,16 @@ msgstr "Příklad množného čísla:"
 msgid "Today is {0}"
 msgstr "Dnes je {0}"
 
+#: src/App.tsx:49
+msgctxt "example ctxt"
+msgid "Context example:"
+msgstr "Kontext příklad:"
+
+#: src/App.tsx:52
+msgctxt "example ctxt"
+msgid "Hello World"
+msgstr "Ahoj Kontext"
+
 #: src/App.tsx:31
 msgid "{count, plural, zero {There are no books} one {There's one book} other {There are # books}}"
 msgstr "{count, plural, zero {Nejsou žádné knihy} one {Je tu jedna kniha} other {Existuje # knih}}"

examples/create-react-app/src/locales/en/messages.po

@@ -21,6 +21,10 @@ msgstr "Date formatter example:"
 msgid "Decrement"
 msgstr "Decrement"
 
+#: src/App.tsx:51
+msgid "Hello World"
+msgstr "Hello World"
+
 #: src/App.tsx:45
 msgid "I have a balance of {0}"
 msgstr "I have a balance of {0}"
@@ -45,6 +49,16 @@ msgstr "Plurals example:"
 msgid "Today is {0}"
 msgstr "Today is {0}"
 
+#: src/App.tsx:49
+msgctxt "example ctxt"
+msgid "Context example:"
+msgstr "Context example:"
+
+#: src/App.tsx:52
+msgctxt "example ctxt"
+msgid "Hello World"
+msgstr "Hello Context"
+
 #: src/App.tsx:31
 msgid "{count, plural, zero {There are no books} one {There's one book} other {There are # books}}"
 msgstr "{count, plural, zero {There are no books} one {There's one book} other {There are # books}}"

packages/babel-plugin-extract-messages/src/index.ts

@@ -28,7 +28,7 @@ function addMessage(
     if (messages.has(context)) {
       const existingContext = messages.get(context)
       if (existingContext.has(id)) {
-        const message = messages.get(id)
+        const message = existingContext.get(id)
         // only set/check default language when it's defined.
         if (message.message && newDefault && message.message !== newDefault) {
           throw path.buildCodeFrameError(

packages/babel-plugin-extract-messages/test/__snapshots__/index.ts.snap

@@ -53,6 +53,10 @@ Object {
           js-with-macros.js,
           39,
         ],
+        Array [
+          js-with-macros.js,
+          44,
+        ],
       ],
     },
   },
@@ -62,7 +66,7 @@ Object {
       origin: Array [
         Array [
           js-with-macros.js,
-          44,
+          49,
         ],
       ],
     },

packages/babel-plugin-extract-messages/test/fixtures/js-with-macros.js

@@ -41,6 +41,11 @@ const tWithContextB = t({
   context: "Context1"
 })
 
+const tWithContextSameAsB = t({
+  id: "Some other ID",
+  context: "Context1"
+})
+
 const defineMessageWithContext = defineMessage({
   id: "Some ID",
   context: "Context2"