From bcd88bb8e74c4eab58cc2002951355496db72dcf Mon Sep 17 00:00:00 2001
From: Augustine Kim <augustinekim@google.com>
Date: Wed, 31 Jan 2024 09:52:35 -0800
Subject: [PATCH] [docs/localization] Update info on messages that map to the
 same id (#1301)

---
 .../site/docs/v2/localization/overview.md     | 26 ++++++++++++++-----
 .../site/docs/v3/localization/overview.md     | 20 ++++++++++----
 2 files changed, 34 insertions(+), 12 deletions(-)

diff --git a/packages/lit-dev-content/site/docs/v2/localization/overview.md b/packages/lit-dev-content/site/docs/v2/localization/overview.md
index f19a7bed9..b69440098 100644
--- a/packages/lit-dev-content/site/docs/v2/localization/overview.md
+++ b/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,7 +539,6 @@ 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:
@@ -545,7 +546,6 @@ 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`
diff --git a/packages/lit-dev-content/site/docs/v3/localization/overview.md b/packages/lit-dev-content/site/docs/v3/localization/overview.md
index aefc4a87a..4d64dd7f7 100644
--- a/packages/lit-dev-content/site/docs/v3/localization/overview.md
+++ b/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,7 +539,6 @@ 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:
@@ -547,7 +546,6 @@ 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`