docs: for localization update explaining how variable interpolation works in template files (#1404)

Author: jimmont

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

@@ -164,6 +164,56 @@ render() {
 }
 ```
 
+## Document Variable Positions in Locale Files
+
+When working with templates containing multiple variables, it's important to remember that locale files use positional references (`${0}`, `${1}`, etc.) rather than variable names. Consider adding comments to your locale files to make variable positions clear:
+
+```js
+export const templates = {
+  // ${0} = username, ${1} = count, ${2} = repo name
+  commit_message: html`${0} made ${1} commits to ${2}`,
+
+  // ${0} = error code, ${1} = error message
+  error_template: html`Error ${0}: ${1}`
+}
+```
+
+This documentation helps translators understand the context of each variable and reduces errors when working with complex templates across multiple locales.
+
+### Consider Variable Order in Your Template Design
+
+When designing localizable templates, be mindful that different languages may require different variable orders. To make localization easier:
+
+1. Design templates with clear, separable variables
+2. Avoid grammatical constructions that rely on specific word order
+3. Use IDs for templates that may need reordering of variables
+4. Test your UI with locales that have very different grammar structures
+
+For example, this approach gives translators maximum flexibility:
+
+```js
+/* In your component */
+msg(html`${username} sent ${fileCount} files to ${recipient}`, {
+  id: 'file_transfer',
+  desc: 'Message displayed after a successful file transfer'
+});
+
+/* In your locale files */
+// English (follows Subject-Verb-Object order)
+export const templates = {
+  file_transfer: html`${0} sent ${1} files to ${2}`
+}
+
+// Japanese (follows Subject-Object-Verb order)
+export const templates = {
+  file_transfer: html`${0}が${2}に${1}個のファイルを送信しました`
+}
+```
+
+In this example, the variables can be placed in whatever order is grammatically correct for each language, making for a more natural user experience across different locales.
+
+These practices make your application more resilient to the linguistic variations across different locales.
+
 ## Safely re-exporting or re-assigning localize APIs
 
 Static analysis is used to determine when you are calling the `@lit/localize`

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

@@ -135,6 +135,51 @@ Localized messages can also be nested inside HTML templates:
 html`<button>${msg('Hello World')}</button>`;
 ```
 
+### Template Variable References in Locale Files
+
+While template expressions in your component code use named variables (e.g., `${name}`, `${count}`),
+templates within locale files use **positional parameters** (`${0}`, `${1}`, etc.) rather than variable names.
+
+When a template with an `id` is processed, variables are passed to the localized template in the
+order they appear in the original template, and are referenced by their index:
+
+```js
+/* In your component */
+const address = 'user@host';
+msg(str`checking...${address}`, {id: 'check_email'});
+
+/* In your locale file (e.g., locales/en.js) */
+export const templates = {
+  check_email: html`checking ${0}`
+}
+```
+
+This positional referencing allows translators to reorder variables when needed for different languages:
+
+```js
+/* In your component */
+const name = 'Maria';
+const count = 42;
+msg(str`${name} has ${count} messages`, {id: 'user_messages'});
+
+/* In your locale file */
+export const templates = {
+  user_messages: html`${0} has ${1} messages`,
+  // For languages where order might need to change:
+  user_messages_reordered: html`Messages (${1}) for ${0}`
+}
+```
+
+<div class="alert alert-info">
+
+Note that the numeric references (${0}, ${1}, etc.) correspond to the order of variables
+in the original template, not their position in the resulting string.
+
+</div>
+
+For more examples of localized templates, see the [runtime mode](/docs/v3/localization/runtime-mode) page.
+
+
 ### Strings with expressions
 
 Strings that contain an expression must be tagged with either `html` or `str` in
@@ -237,7 +282,9 @@ compared to transform mode.
 ```js
 // locales/es-419.ts
 export const templates = {
+  // These IDs are automatically generated from template content
   hf71d669027554f48: html`Hola <b>Mundo</b>`,
+  saed7d3734ce7f09d: html`Hola ${0}`, // Note: Variable references use numeric positions
 };
 ```
 

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

@@ -140,6 +140,40 @@ customElements.define('my-element', MyElement);
 
 {% endswitchable-sample %}
 
+## Working with Variables in Templates
+
+When working with templates in runtime mode, remember that variables in locale files use positional references:
+
+```js
+// In your component
+msg(html`<div>User ${userName} made ${count} commits</div>`, {id: 'user_activity'});
+
+// In your locale file (e.g., locales/en.js)
+export const templates = {
+  user_activity: html`<div>User ${0} made ${1} commits</div>`
+}
+
+// In another locale file (e.g., locales/ja.js) - order can change if needed
+export const templates = {
+  user_activity: html`<div>${0}さんは${1}回コミットしました</div>`
+}
+```
+
+This numeric referencing system becomes especially important when:
+
+1. Translating to languages with different word orders
+2. Working with formats that have placeholders in different positions
+3. Implementing plural forms that may rearrange variables
+
+For more complex templates with many variables, consider adding descriptive comments in your locale files to help translators understand which position corresponds to which variable:
+
+```js
+export const templates = {
+  // ${0} = userName, ${1} = count
+  user_activity: html`<div>User ${0} made ${1} commits</div>`
+}
+```
+
 ## Status event
 
 The `lit-localize-status` event fires on `window` whenever a locale switch