[docs/localization] Update info on messages that map to the same id (#1301)

Author: augustjk

packages/lit-dev-content/site/docs/v2/localization/overview.md

@@ -362,7 +362,8 @@ blank.
   "tsConfig": "./tsconfig.json",
   "output": {
     "mode": "runtime",
-    "outputDir": "./src/generated/locales"
+    "outputDir": "./src/generated/locales",
+    "localeCodesModule": "./src/generated/locale-codes.ts"
   },
   "interchange": {
     "format": "xliff",
@@ -381,7 +382,8 @@ blank.
   ],
   "output": {
     "mode": "runtime",
-    "outputDir": "./src/generated/locales"
+    "outputDir": "./src/generated/locales",
+    "localeCodesModule": "./src/generated/locale-codes.js"
   },
   "interchange": {
     "format": "xliff",
@@ -500,7 +502,7 @@ Descriptions are represented in XLIFF files using `<note>` elements.
 ```xml
 <trans-unit id="s512957aa09384646">
   <source>Launch</source>
-  <note>Button that begins rocket launch sequence.</note>
+  <note from="lit-localize">Button that begins rocket launch sequence.</note>
 </trans-unit>
 ```
 
@@ -518,10 +520,10 @@ have the same content they will be treated as one message:
 
 ```js
 // file1.js
-msg('Hello World')
+msg('Hello World');
 
 // file2.js
-msg('Hello World')
+msg('Hello World');
 ```
 
 ### ID generation
@@ -537,15 +539,13 @@ The following content **does not** affect ID generation:
 
 - The code inside an expression
 - The computed value of an expression
-- Descriptions
 - File location
 
 For example, all of these messages share the same ID:
 
 ```js
 msg(html`Hello <b>${name}</b>`);
 msg(html`Hello <b>${this.name}</b>`);
-msg(html`Hello <b>${this.name}</b>`, {desc: 'A friendly greeting'});
 ```
 
 But this message has a different ID:
@@ -554,6 +554,18 @@ But this message has a different ID:
 msg(html`Hello <i>${name}</i>`);
 ```
 
+Note, while providing a [description](#message-descriptions) does not affect ID
+generation, multiple messages with the same ID but different description will
+produce an error during analysis to avoid ambiguity in the extracted translation
+unit. The following is considered **invalid**:
+
+```js
+msg(html`Hello <b>${name}</b>`);
+msg(html`Hello <b>${name}</b>`, {desc: 'A friendly greeting'});
+```
+
+Make sure that all messages with the same ID also have the same description.
+
 ### Overriding IDs
 
 Message IDs can be overridden by specifying the `id` option to the `msg`

packages/lit-dev-content/site/docs/v3/localization/overview.md

@@ -502,7 +502,7 @@ Descriptions are represented in XLIFF files using `<note>` elements.
 ```xml
 <trans-unit id="s512957aa09384646">
   <source>Launch</source>
-  <note>Button that begins rocket launch sequence.</note>
+  <note from="lit-localize">Button that begins rocket launch sequence.</note>
 </trans-unit>
 ```
 
@@ -520,10 +520,10 @@ have the same content they will be treated as one message:
 
 ```js
 // file1.js
-msg('Hello World')
+msg('Hello World');
 
 // file2.js
-msg('Hello World')
+msg('Hello World');
 ```
 
 ### ID generation
@@ -539,15 +539,13 @@ The following content **does not** affect ID generation:
 
 - The code inside an expression
 - The computed value of an expression
-- Descriptions
 - File location
 
 For example, all of these messages share the same ID:
 
 ```js
 msg(html`Hello <b>${name}</b>`);
 msg(html`Hello <b>${this.name}</b>`);
-msg(html`Hello <b>${this.name}</b>`, {desc: 'A friendly greeting'});
 ```
 
 But this message has a different ID:
@@ -556,6 +554,18 @@ But this message has a different ID:
 msg(html`Hello <i>${name}</i>`);
 ```
 
+Note, while providing a [description](#message-descriptions) does not affect ID
+generation, multiple messages with the same ID but different description will
+produce an error during analysis to avoid ambiguity in the extracted translation
+unit. The following is considered **invalid**:
+
+```js
+msg(html`Hello <b>${name}</b>`);
+msg(html`Hello <b>${name}</b>`, {desc: 'A friendly greeting'});
+```
+
+Make sure that all messages with the same ID also have the same description.
+
 ### Overriding IDs
 
 Message IDs can be overridden by specifying the `id` option to the `msg`