From 831c5e3b6fe2dc635bdfa32b97e71acfcaaa5750 Mon Sep 17 00:00:00 2001 From: Jim Montgomery Date: Thu, 27 Mar 2025 14:33:33 +0800 Subject: [PATCH] docs: for localization update explaining how variable interpolation works in template files (#1404) --- .../docs/v3/localization/best-practices.md | 50 +++++++++++++++++++ .../site/docs/v3/localization/overview.md | 47 +++++++++++++++++ .../site/docs/v3/localization/runtime-mode.md | 34 +++++++++++++ 3 files changed, 131 insertions(+) diff --git a/packages/lit-dev-content/site/docs/v3/localization/best-practices.md b/packages/lit-dev-content/site/docs/v3/localization/best-practices.md index a7413d9c3..9c4363abb 100644 --- a/packages/lit-dev-content/site/docs/v3/localization/best-practices.md +++ b/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` 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 4d64dd7f7..7e8e6170d 100644 --- a/packages/lit-dev-content/site/docs/v3/localization/overview.md +++ b/packages/lit-dev-content/site/docs/v3/localization/overview.md @@ -135,6 +135,51 @@ Localized messages can also be nested inside HTML templates: html``; ``` +### 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}` +} +``` + +
+ +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. + +
+ +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 Mundo`, + saed7d3734ce7f09d: html`Hola ${0}`, // Note: Variable references use numeric positions }; ``` diff --git a/packages/lit-dev-content/site/docs/v3/localization/runtime-mode.md b/packages/lit-dev-content/site/docs/v3/localization/runtime-mode.md index 67d2ad1e7..bbfdcaf99 100644 --- a/packages/lit-dev-content/site/docs/v3/localization/runtime-mode.md +++ b/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`
User ${userName} made ${count} commits
`, {id: 'user_activity'}); + +// In your locale file (e.g., locales/en.js) +export const templates = { + user_activity: html`
User ${0} made ${1} commits
` +} + +// In another locale file (e.g., locales/ja.js) - order can change if needed +export const templates = { + user_activity: html`
${0}さんは${1}回コミットしました
` +} +``` + +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`
User ${0} made ${1} commits
` +} +``` + ## Status event The `lit-localize-status` event fires on `window` whenever a locale switch