From 23016815c9d872249c83a953a5be30068231dbc6 Mon Sep 17 00:00:00 2001 From: Sandro Danioth Date: Sat, 28 Feb 2026 00:58:24 +0100 Subject: [PATCH 01/21] docs(localization): first version of localization guide for UX writers --- docs/fundamentals/localization.md | 377 ++++++++++++++++++++++++++++-- 1 file changed, 360 insertions(+), 17 deletions(-) diff --git a/docs/fundamentals/localization.md b/docs/fundamentals/localization.md index 36f5f34784..db44a885b4 100644 --- a/docs/fundamentals/localization.md +++ b/docs/fundamentals/localization.md @@ -1,7 +1,354 @@ + + # Localization -Localization or internationalization (i18n) is the process of designing and preparing your app to be usable in different locales around the world. -Localization includes the support for different languages as well as different formats for entities like dates, time, decimals, currency, etc. +Localization (l10n) or internationalization (i18n) is the process of designing and implementing a product for a **specific language and region**. + +## Introduction --- + +!!! tip "Localization is more than just translate the text" + + - It covers translation, but also **formats** (date/time/number), **script direction** (LTR/RTL), and UI behavior in different languages. + - The **same English word** can require different words in other languages depending on meaning (ambiguity). + - Languages differ in **word order**, **plural rules**, and **punctuation**. + - UI text can **grow** (sometimes a lot), wrap, or break layouts. + + + +## UX Writing --- + + +Localization is mainly a [development task](#code) but UX writers can support developers. + + +User interface texts are stand-alone, short and to the point, but without context. Thus, AI can produce a reliable translation only, the terms must be + +- [Dominant](#terms-in-various-uses) +- [Precise](#terminology) +- [Unambiguous](#remove-ambiguity) + +UX writing *combines* terminology, style, and form… + +- to apply *consistent terms* on a UI +- to apply a *consistent style* on a UI +- to apply a *consistent form* on a UI + +…for specific *use cases*, fully focused on the *target audience* (personas) + +!!! tip "Think like a translator" + + Every string will be translated without access to the surrounding UI. Ask yourself: is this text understandable **without visual context**? + +
+
+ + #### Do's + + - `Delete template for tool instance IDs` + +
+
+ + #### Don'ts + + - `Delete complete tool instance ID naming`Deleting a tool instance?
Naming something?
Is "complete" an adjective or a verb? + +
+
+ +### Terminology + +When a term is *defined*, it explains what it is (not does). + +Terms are defined by experts in the related fields (physicists, engineers…), universities teaching/researching specific domains, legal fields, experts at various companies worldwide specializing in specific domains (e.g. Siemens, Honeywell, etc.), standardization bodies (e.g. ISO, EN, UL, BS, DIN, ASHRAE, BACnet etc. comprised of corporate experts, universities) +Quasi-industrial standards from individual sources (Haystack, Bric etc.) become international standards only if aligned to official organizations. If not aligned, setting a standard remains wishful thinking + +Common language serves multiple purposes: + +- *Clarity of communication*, common understanding between people and companies +- *Applicability* across multiple systems/tools/hardware… +- *Openness* to third parties, breaking up of silos +- Foundation for *artificial intelligence* + +!!! warning "Usage of terminology databases" + + - Select the terminology of your business. + - Identify terms not yet defined and request them. + +#### Terms in various uses + +Many terms have various meanings related to a specific context or domain. + +*One meaning always dominates* regardless of context. That is the meaning that can be used without creating confusion. However, if that meaning does not fit the context, an alternative term (unambiguous synonym) must be used to eliminate misunderstandings + +In addition, the alternative term increases substantially the probability of correct interpretation by artificial intelligence (as part of translation, machine learning, or any other use) + +### Remove ambiguity + +The ambiguity can be removed by + +- grouping the texts by use cases (namespaces) +- only using [dominant meaning](#terms-in-various-uses) of term + +#### Grouping of texts + +Group texts by use case and provide meaningful (key) names. + +
+
+ +#### Do's + +- `"ACCOUNT.LOGOUT.CANCEL":` "Cancel", +- `"ACCOUNT.LOGOUT.HEADING":` "Log out", +- `"ACCOUNT.LOGOUT.LOG_OUT_NOW":` "Log out now?", +- `"ACCOUNT.LOGOUT.LOGGING_OUT":` "Logging out…", +- `"ACCOUNT.SETTINGS.HEADING":` "Settings", +- `"ACCOUNT.SETTINGS.THEME":` "Theme", +- `"ACCOUNT.SETTINGS.THEME_OPTIONS.AUTO":` "Auto", +- `"ACCOUNT.SETTINGS.THEME_OPTIONS.DARK":` "Dark", +- `"ACCOUNT.SETTINGS.THEME_OPTIONS.LIGHT":` "Light", +- `"LEGAL.ABOUT":` "About", +- `"LEGAL.IMPRINT":` "Corporate Information", +- `"LEGAL.PRIVACY_POLICY":` "Privacy Notice", +- `"LEGAL.VERSION":` "Version {{version}}" + +
+
+ +#### Don'ts + +- `"ABOUT":` "About", +- `"AUTO":` "Auto", +- `"CANCEL":` "Cancel", +- `"DARK":` "Dark", +- `"IMPRINT":` "Corporate Information", +- `"LIGHT":` "Light", +- `"LOG_OUT_NOW":` "Log out now?", +- `"LOGGING_OUT":` "Logging out…", +- `"LOGOUT":` "Log out", +- `"PRIVACY_POLICY":` "Privacy Notice", +- `"SETTINGS":` "Settings", +- `"THEME":` "Theme", +- `"VERSION":` "Version {{version}}" + +
+
+ +### Reuse strings + +Before writing a new string, check whether one with the exact meaning already exists. + +Reusing strings… + +- …reduces the volume sent to translators and lowers cost. +- …gains efficiency. +- …keeps translation unique in every supported language. +- …supports the `ONE Tech company` initiative. + +!!! warning "Context-dependent strings" + + A single string reused across different contexts may require different translations in different languages. + + In doubt, create a separate string for each use even if the English text looks the same. + +### Use translation libraries + +[Unicode CLDR](https://cldr.unicode.org/) provides high quality translations for: + +- language and script names +- countries and regions +- currencies +- months, weekdays and time zones + +Use these sources to avoid superfluous translate effort. + +### Provide user-friendly language selection + +Provide the languages in the target language for the language switcher. + +
+
+ +#### Do's + +- English +- Deutsch +- Français +- Italiano +- Ελληνικά +- 中文 + +
+
+ +#### Don'ts + +- 英语 +- 德语 +- 法语 +- 意大利语 +- 希腊 +- 中文 + +
+
+ +### Avoid string concatenations + +Building sentences from fragments prevents correct grammar in many languages. +Keep sentences as one unit with placeholders. + + + +
+
+ +#### Do's + +- EN: `Select site {site} of {company}?` +- DE: `Standort {site} von {company} auswählen?` + +
+
+ +#### Don'ts + +- EN: `Select site ` + `{site}` + ` of ` + `{company}` + `?` +- DE: `Standort auswählen ` + `{site}` + ` von ` + `{company}` + `?` + +
+
+ + + +### Define understandable placeholders + +Keep sentence understandable even with placeholders. + +
+
+ +#### Do's + +- `Reactivating site {name} within activation period: {startDate} – {endDate}` + +
+
+ +#### Don'ts + +- `Reactivating site {1} within activation period: {2} – {3}` + +
+
+ +### Avoid hard-coding formats + + +Use locale-aware formatting (see [Code tab](#code)), and avoid UX writing depending on a single format. + +
+
+ +#### Do's + +- Use localization framework (see [Code tab](#code)) +- Use [placeholders](#define-understandable-placeholders) in text: `Saved on {date}` + +
+
+ +#### Don'ts + +- `02/03/2026` (ambiguous) +- `1,234.56` everywhere + +
+
+ + + +### Pluralization + +The correct translation of texts which relate to a count differs in different languages. + +Pluralization of the `English` term «apple»: + +- 1: «I own one apple.» +- n: «I own four apples.» + +Pluralization of the `Polish` term «Plik» (`English`: «file»): + +- 1 plik +- 2, 3, 4 pliki +- 5-21 plików +- 22-24 pliki +- 25-31 plików + +#### Handling of zero + +The count 0 is handled differently in several languages. + +
+
+ +#### Do's + +- Ich besitze keinen Apfel. («Apfel» | `EN`: «apple» in singular) + +
+
+ +#### Don'ts + +- Ich besitze 0 Äpfel («Äpfel» | `EN`: «apples» in plural) + +
+
+ +#### Linguistic rules + +Depending on the language there might be up to 6 forms. Following language specific variability does exist: + +| Forms | Grammatical rules | Languages | +|:-----:|---------------------------------------------------------------------------------------------------------------------|-----------------| +| 1 | No distinction between the singular and plural form | e.g. Japanese | +| 2 | Singular used for one only | e.g. English | +| 2 | Singular used for zero and one | e.g. French | +| 3 | Special case for zero | Latvian | +| 3 | Special cases for one and two | Gaelic (Irish) | +| 3 | Special case for numbers ending in `00` or `[2-9][0-9]` | Romanian | +| 3 | Special case for numbers ending in `1[2-9]` | Lithuanian | +| 3 | Special cases for numbers ending in `1` and `2`, `3`, `4`, except those ending in `1[1-4]` | e.g. Russian | +| 3 | Special cases for `1` and `2`, `3`, `4` | e.g. Czech | +| 3 | Special case for one and some numbers ending in `2`, `3`, or `4` | Polish | +| 4 | Special case for one and all numbers ending in `02`, `03`, or `04` | Slovenian | +| 6 | Special cases for one, two, all numbers ending in `02`, `03`, … `10`, all numbers ending in `11` … `99`, and others | Arabic | + +#### Use localization to handle pluralization + +Pluralization cannot be handled by product code or writing style. Use localization (e.g., ICU or framework plural rules) instead. + +
+
+ +#### Do's + +- `{count} rows` + +
+
+ +#### Don'ts + +- `{count} row(s)` +- if (count == 1) {`1 row`} else {`{count} rows`} + +
+
+ +## Code --- Angular supports localization as described in the [i18n](https://angular.dev/guide/i18n) guide and is supported by [pipes](https://angular.dev/guide/templates/pipes). Angular applies a compile time localization concept. It does not support the change of locales (language and formats) at runtime. Instead, for each locale @@ -20,9 +367,7 @@ the inputs changes. This means they do not re-render when the `LOCALE_ID` change We recommend to follow the same behavior as users changes to locales are seldom. As a consequence we need to reload the web application on locale changes. - - -## Locales in Element +### Locales in Element Element provides the service `SiLocaleService` to set the current locale like `en`, `fr` or a variant like `fr-CA` or `en-GB` as well as the available locales of the application. The service is @@ -70,7 +415,7 @@ export const APP_CONFIG: ApplicationConfig = { In addition, `fallbackEnabled` enables ngx-translate to use the translation from the `defaultLocale` language when a translate value is missing. -## Persisting locales using SiLocaleStore +### Persisting locales using SiLocaleStore Setting the `SiLocaleService.locale = 'fr'` changes the language and forces a reload of the browser window. The service uses the `SiLocaleStore` to persist the new locale. After reloading the application, the service uses the `SiLocaleStore` to load @@ -108,7 +453,7 @@ export const APP_CONFIG: ApplicationConfig = { You can also combine a Store that caches the last value in the localStore and loads in parallel the current value from a backend. -## Runtime locales changes using impure pipes +### Runtime locales changes using impure pipes If you need to support locale changes without reloading, we recommend to extend the Angular pipes and set the `pure` property to false. @@ -120,13 +465,13 @@ If you need to support locale changes without reloading, we recommend to extend export class DateImpurePipe extends DatePipe implements PipeTransform {} ``` -## Translation in Element +### Translation in Element Element >= v43 includes a translation abstraction layer which allows us to support multiple translation frameworks. There is no hard dependency to a specific translation library anymore. Therefore, by default, translation keys (`TranslatableString`) will no longer be translated. -### Supported Frameworks +#### Supported Frameworks If a translation framework is used, Element must be configured to use this framework as well. For module-based applications, the respective module must be imported in the root module. @@ -141,8 +486,6 @@ Supported frameworks: | `ngx-translate` | `@siemens/element-translate-ng/ngx-translate` | `SiTranslateNgxTModule` | `provideNgxTranslateForElement` | | | `@angular/localize` | `@siemens/element-translate-ng/angular-localize` | `SiTranslateNgLocalizeModule` | `provideNgLocalizeForElement` | The support is experimental. Please reach out to us via an issue, if you plan to use this in a productive app. | - - Remember, this is only the activation of the respective layer for Element, you still need to import and configure the framework in your application as you would normally do. @@ -152,13 +495,13 @@ If no framework is configured, Element will fall back to English. Support for `@ngneat/transloco` and other frameworks might be added in the future on request. -### Overriding default text keys globally +#### Overriding default text keys globally Element provides the possibility to override text keys on a global level. This can be used to change the default value of text keys that are used multiple times within an application but have most likely the same value. This is usually the case for static labels like `Close`, `Ok`, ... -All keys that can be overridden can be found [here.](https://element.siemens.io/api/element-ng/types/SiTranslatableKeys) +See [overridable strings from Element](https://element.siemens.io/api/element-ng/types/SiTranslatableKeys) for details. The overriding of text keys is available for every framework except `@angular/localize` due to technical limitations. @@ -177,7 +520,7 @@ import { provideSiTranslatableOverrides } from '@siemens/element-ng/translate'; export class AppModule {} ``` -### How it works +#### How it works Within Element, a `TranslatableString` is declared using a syntax based on `@angular/localize`: @@ -199,7 +542,7 @@ be [overridden by a global provider](#overriding-default-text-keys-globally). The `translate` pipe is needed for frameworks like `ngx-translate` where translation happens at runtime. It resolves a `TranslatableString` generated by `$localize` using an actual translation framework. -### Default text with @ngx-translate/core +#### Default text with @ngx-translate/core During application development, translations may be missing for certain translation keys, especially when adding new features or supporting additional languages. Without proper handling, missing translations can result in translation keys being displayed directly to users instead of meaningful text. @@ -232,7 +575,7 @@ export const appConfig: ApplicationConfig = { }; ``` -### Adding Cache busting feature to the translation \*.json files +#### Adding Cache busting feature to the translation \*.json files By default, the `*.json` files used for translation, are not hashed by Webpack during the build and may cause caching issues when newer versions of the applications are deployed. To counter this, we can either use the bundler to load translations @@ -261,6 +604,6 @@ Note that this hash key will only be appended to the translation based JSON file -### Translatable keys in Element +#### Translatable keys in Element From cd5d844dabc1b18c6f2adedba5c13d78d02c87ea Mon Sep 17 00:00:00 2001 From: Sandro Danioth Date: Sat, 28 Feb 2026 10:06:42 +0100 Subject: [PATCH 02/21] chore(localization): shorten sentences --- docs/fundamentals/localization.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/fundamentals/localization.md b/docs/fundamentals/localization.md index db44a885b4..586a324752 100644 --- a/docs/fundamentals/localization.md +++ b/docs/fundamentals/localization.md @@ -58,10 +58,9 @@ UX writing *combines* terminology, style, and form… ### Terminology -When a term is *defined*, it explains what it is (not does). - -Terms are defined by experts in the related fields (physicists, engineers…), universities teaching/researching specific domains, legal fields, experts at various companies worldwide specializing in specific domains (e.g. Siemens, Honeywell, etc.), standardization bodies (e.g. ISO, EN, UL, BS, DIN, ASHRAE, BACnet etc. comprised of corporate experts, universities) -Quasi-industrial standards from individual sources (Haystack, Bric etc.) become international standards only if aligned to official organizations. If not aligned, setting a standard remains wishful thinking +- Terms are defined by experts in the related fields (physicists, engineers…), universities teaching/researching specific domains, legal fields, experts at various companies worldwide specializing in specific domains (e.g. Siemens, Honeywell, etc.). +- Standardization bodies (e.g., ISO, EN, UL, BS, DIN, ASHRAE, BACnet), comprised of corporate experts and universities are standardizing common terms. +- Quasi-industrial standards from individual sources (Haystack, Bric etc.) become international standards only if aligned to official organizations. If not aligned, setting a standard remains wishful thinking. Common language serves multiple purposes: From 42bb9b1f69768e345b2425382293cff73f814b2f Mon Sep 17 00:00:00 2001 From: Sandro Danioth Date: Mon, 2 Mar 2026 12:40:37 +0100 Subject: [PATCH 03/21] docs(localization): fix (most) formating issues --- docs/fundamentals/localization.md | 61 ++++++++++++++++--------------- 1 file changed, 32 insertions(+), 29 deletions(-) diff --git a/docs/fundamentals/localization.md b/docs/fundamentals/localization.md index 586a324752..1b5f251377 100644 --- a/docs/fundamentals/localization.md +++ b/docs/fundamentals/localization.md @@ -18,7 +18,9 @@ Localization (l10n) or internationalization (i18n) is the process of designing a ## UX Writing --- + Localization is mainly a [development task](#code) but UX writers can support developers. + User interface texts are stand-alone, short and to the point, but without context. Thus, AI can produce a reliable translation only, the terms must be @@ -27,13 +29,13 @@ User interface texts are stand-alone, short and to the point, but without contex - [Precise](#terminology) - [Unambiguous](#remove-ambiguity) -UX writing *combines* terminology, style, and form… +UX writing _combines_ terminology, style, and form… -- to apply *consistent terms* on a UI -- to apply a *consistent style* on a UI -- to apply a *consistent form* on a UI +- to apply _consistent terms_ on a UI +- to apply a _consistent style_ on a UI +- to apply a _consistent form_ on a UI -…for specific *use cases*, fully focused on the *target audience* (personas) +…for specific _use cases_, fully focused on the _target audience_ (personas) !!! tip "Think like a translator" @@ -41,18 +43,18 @@ UX writing *combines* terminology, style, and form…
- + #### Do's - `Delete template for tool instance IDs`
- + #### Don'ts - `Delete complete tool instance ID naming`Deleting a tool instance?
Naming something?
Is "complete" an adjective or a verb? - +
@@ -64,21 +66,21 @@ UX writing *combines* terminology, style, and form… Common language serves multiple purposes: -- *Clarity of communication*, common understanding between people and companies -- *Applicability* across multiple systems/tools/hardware… -- *Openness* to third parties, breaking up of silos -- Foundation for *artificial intelligence* +- _Clarity of communication_, common understanding between people and companies +- _Applicability_ across multiple systems/tools/hardware… +- _Openness_ to third parties, breaking up of silos +- Foundation for _artificial intelligence_ !!! warning "Usage of terminology databases" - Select the terminology of your business. - Identify terms not yet defined and request them. - + #### Terms in various uses Many terms have various meanings related to a specific context or domain. -*One meaning always dominates* regardless of context. That is the meaning that can be used without creating confusion. However, if that meaning does not fit the context, an alternative term (unambiguous synonym) must be used to eliminate misunderstandings +_One meaning always dominates_ regardless of context. That is the meaning that can be used without creating confusion. However, if that meaning does not fit the context, an alternative term (unambiguous synonym) must be used to eliminate misunderstandings In addition, the alternative term increases substantially the probability of correct interpretation by artificial intelligence (as part of translation, machine learning, or any other use) @@ -148,7 +150,7 @@ Reusing strings… !!! warning "Context-dependent strings" A single string reused across different contexts may require different translations in different languages. - + In doubt, create a separate string for each use even if the English text looks the same. ### Use translation libraries @@ -245,6 +247,7 @@ Keep sentence understandable even with placeholders. ### Avoid hard-coding formats + Use locale-aware formatting (see [Code tab](#code)), and avoid UX writing depending on a single format.
@@ -310,20 +313,20 @@ The count 0 is handled differently in several languages. Depending on the language there might be up to 6 forms. Following language specific variability does exist: -| Forms | Grammatical rules | Languages | -|:-----:|---------------------------------------------------------------------------------------------------------------------|-----------------| -| 1 | No distinction between the singular and plural form | e.g. Japanese | -| 2 | Singular used for one only | e.g. English | -| 2 | Singular used for zero and one | e.g. French | -| 3 | Special case for zero | Latvian | -| 3 | Special cases for one and two | Gaelic (Irish) | -| 3 | Special case for numbers ending in `00` or `[2-9][0-9]` | Romanian | -| 3 | Special case for numbers ending in `1[2-9]` | Lithuanian | -| 3 | Special cases for numbers ending in `1` and `2`, `3`, `4`, except those ending in `1[1-4]` | e.g. Russian | -| 3 | Special cases for `1` and `2`, `3`, `4` | e.g. Czech | -| 3 | Special case for one and some numbers ending in `2`, `3`, or `4` | Polish | -| 4 | Special case for one and all numbers ending in `02`, `03`, or `04` | Slovenian | -| 6 | Special cases for one, two, all numbers ending in `02`, `03`, … `10`, all numbers ending in `11` … `99`, and others | Arabic | +| Forms | Grammatical rules | Languages | +| :---: | ------------------------------------------------------------------------------------------------------------------- | -------------- | +| 1 | No distinction between the singular and plural form | e.g. Japanese | +| 2 | Singular used for one only | e.g. English | +| 2 | Singular used for zero and one | e.g. French | +| 3 | Special case for zero | Latvian | +| 3 | Special cases for one and two | Gaelic (Irish) | +| 3 | Special case for numbers ending in `00` or `[2-9][0-9]` | Romanian | +| 3 | Special case for numbers ending in `1[2-9]` | Lithuanian | +| 3 | Special cases for numbers ending in `1` and `2`, `3`, `4`, except those ending in `1[1-4]` | e.g. Russian | +| 3 | Special cases for `1` and `2`, `3`, `4` | e.g. Czech | +| 3 | Special case for one and some numbers ending in `2`, `3`, or `4` | Polish | +| 4 | Special case for one and all numbers ending in `02`, `03`, or `04` | Slovenian | +| 6 | Special cases for one, two, all numbers ending in `02`, `03`, … `10`, all numbers ending in `11` … `99`, and others | Arabic | #### Use localization to handle pluralization From 6013379c2b7d792e43dab7122ad1983013362a20 Mon Sep 17 00:00:00 2001 From: Sandro Danioth Date: Mon, 2 Mar 2026 16:52:12 +0100 Subject: [PATCH 04/21] docs(localization): make linter happy but author unhappy --- docs/fundamentals/localization.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/fundamentals/localization.md b/docs/fundamentals/localization.md index 1b5f251377..f28352fdfe 100644 --- a/docs/fundamentals/localization.md +++ b/docs/fundamentals/localization.md @@ -215,8 +215,8 @@ Keep sentences as one unit with placeholders. #### Don'ts -- EN: `Select site ` + `{site}` + ` of ` + `{company}` + `?` -- DE: `Standort auswählen ` + `{site}` + ` von ` + `{company}` + `?` +- EN: `Select site ` + `{site}` + `of` + `{company}` + `?` +- DE: `Standort auswählen ` + `{site}` + `von` + `{company}` + `?`
From 93101306b2d1cb28de30a5e68b80abc3760a6dca Mon Sep 17 00:00:00 2001 From: Sandro Danioth Date: Tue, 3 Mar 2026 08:52:56 +0100 Subject: [PATCH 05/21] chore(localization): correct spelling mistakes Co-authored-by: Daniel Ritz --- docs/fundamentals/localization.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/fundamentals/localization.md b/docs/fundamentals/localization.md index f28352fdfe..c89cd4419d 100644 --- a/docs/fundamentals/localization.md +++ b/docs/fundamentals/localization.md @@ -44,7 +44,7 @@ UX writing _combines_ terminology, style, and form…
- #### Do's + #### Dos - `Delete template for tool instance IDs` @@ -98,7 +98,7 @@ Group texts by use case and provide meaningful (key) names.
-#### Do's +#### Dos - `"ACCOUNT.LOGOUT.CANCEL":` "Cancel", - `"ACCOUNT.LOGOUT.HEADING":` "Log out", @@ -171,7 +171,7 @@ Provide the languages in the target language for the language switcher.
-#### Do's +#### Dos - English - Deutsch @@ -205,7 +205,7 @@ Keep sentences as one unit with placeholders.
-#### Do's +#### Dos - EN: `Select site {site} of {company}?` - DE: `Standort {site} von {company} auswählen?` @@ -230,7 +230,7 @@ Keep sentence understandable even with placeholders.
-#### Do's +#### Dos - `Reactivating site {name} within activation period: {startDate} – {endDate}` @@ -253,7 +253,7 @@ Use locale-aware formatting (see [Code tab](#code)), and avoid UX writing depend
-#### Do's +#### Dos - Use localization framework (see [Code tab](#code)) - Use [placeholders](#define-understandable-placeholders) in text: `Saved on {date}` @@ -295,7 +295,7 @@ The count 0 is handled differently in several languages.
-#### Do's +#### Dos - Ich besitze keinen Apfel. («Apfel» | `EN`: «apple» in singular) @@ -335,7 +335,7 @@ Pluralization cannot be handled by product code or writing style. Use localizati
-#### Do's +#### Dos - `{count} rows` From 859dc1f06500c1a05b43bed126cf5e8faf09c03e Mon Sep 17 00:00:00 2001 From: Sandro Danioth Date: Wed, 4 Mar 2026 20:20:28 +0100 Subject: [PATCH 06/21] chore(localization): apply several suggestions Co-authored-by: michael-smt <139211597+michael-smt@users.noreply.github.com> --- docs/fundamentals/localization.md | 121 +++++++++++++++--------------- 1 file changed, 59 insertions(+), 62 deletions(-) diff --git a/docs/fundamentals/localization.md b/docs/fundamentals/localization.md index c89cd4419d..d250d2f97c 100644 --- a/docs/fundamentals/localization.md +++ b/docs/fundamentals/localization.md @@ -6,10 +6,10 @@ Localization (l10n) or internationalization (i18n) is the process of designing a ## Introduction --- -!!! tip "Localization is more than just translate the text" +!!! tip "Localization is more than just translating text" - It covers translation, but also **formats** (date/time/number), **script direction** (LTR/RTL), and UI behavior in different languages. - - The **same English word** can require different words in other languages depending on meaning (ambiguity). + - Depending on how it is used, the **same English word** can have multiple meanings and translates to different words in another language. - Languages differ in **word order**, **plural rules**, and **punctuation**. - UI text can **grow** (sometimes a lot), wrap, or break layouts. @@ -29,13 +29,7 @@ User interface texts are stand-alone, short and to the point, but without contex - [Precise](#terminology) - [Unambiguous](#remove-ambiguity) -UX writing _combines_ terminology, style, and form… - -- to apply _consistent terms_ on a UI -- to apply a _consistent style_ on a UI -- to apply a _consistent form_ on a UI - -…for specific _use cases_, fully focused on the _target audience_ (personas) +UX writing combines terminology, [style](ux-text-style-guide/index.md) and form to ensure a consistent UI for specific use cases of a target audience. !!! tip "Think like a translator" @@ -60,8 +54,8 @@ UX writing _combines_ terminology, style, and form… ### Terminology -- Terms are defined by experts in the related fields (physicists, engineers…), universities teaching/researching specific domains, legal fields, experts at various companies worldwide specializing in specific domains (e.g. Siemens, Honeywell, etc.). -- Standardization bodies (e.g., ISO, EN, UL, BS, DIN, ASHRAE, BACnet), comprised of corporate experts and universities are standardizing common terms. +- The terms are defined by experts (physicists, engineers, lawyers, etc.) from universities and various global companies specializing in specific domains. +- Standardization bodies (e.g., ISO, EN, UL, BS, DIN, ASHRAE, BACnet) are standardizing common terms. - Quasi-industrial standards from individual sources (Haystack, Bric etc.) become international standards only if aligned to official organizations. If not aligned, setting a standard remains wishful thinking. Common language serves multiple purposes: @@ -73,8 +67,8 @@ Common language serves multiple purposes: !!! warning "Usage of terminology databases" - - Select the terminology of your business. - - Identify terms not yet defined and request them. + - Select the terminology database of your domain. + - Identify terms not yet defined and request them in the terminology database or by contacting the terminology maintainers of your domain. #### Terms in various uses @@ -82,14 +76,14 @@ Many terms have various meanings related to a specific context or domain. _One meaning always dominates_ regardless of context. That is the meaning that can be used without creating confusion. However, if that meaning does not fit the context, an alternative term (unambiguous synonym) must be used to eliminate misunderstandings -In addition, the alternative term increases substantially the probability of correct interpretation by artificial intelligence (as part of translation, machine learning, or any other use) +In addition, the alternative term substantially increases the probability of correct interpretation by artificial intelligence (as part of translation, machine learning, or any other use). ### Remove ambiguity The ambiguity can be removed by -- grouping the texts by use cases (namespaces) -- only using [dominant meaning](#terms-in-various-uses) of term +- grouping the texts into namespaces by use cases +- only using the [dominant meaning](#terms-in-various-uses) of the term #### Grouping of texts @@ -100,53 +94,53 @@ Group texts by use case and provide meaningful (key) names. #### Dos -- `"ACCOUNT.LOGOUT.CANCEL":` "Cancel", -- `"ACCOUNT.LOGOUT.HEADING":` "Log out", -- `"ACCOUNT.LOGOUT.LOG_OUT_NOW":` "Log out now?", -- `"ACCOUNT.LOGOUT.LOGGING_OUT":` "Logging out…", -- `"ACCOUNT.SETTINGS.HEADING":` "Settings", -- `"ACCOUNT.SETTINGS.THEME":` "Theme", -- `"ACCOUNT.SETTINGS.THEME_OPTIONS.AUTO":` "Auto", -- `"ACCOUNT.SETTINGS.THEME_OPTIONS.DARK":` "Dark", -- `"ACCOUNT.SETTINGS.THEME_OPTIONS.LIGHT":` "Light", -- `"LEGAL.ABOUT":` "About", -- `"LEGAL.IMPRINT":` "Corporate Information", -- `"LEGAL.PRIVACY_POLICY":` "Privacy Notice", -- `"LEGAL.VERSION":` "Version {{version}}" +- `ACCOUNT.LOGOUT.CANCEL:` Cancel +- `ACCOUNT.LOGOUT.HEADING:` Log out +- `ACCOUNT.LOGOUT.LOG_OUT_NOW:` Log out now? +- `ACCOUNT.LOGOUT.LOGGING_OUT:` Logging out… +- `ACCOUNT.SETTINGS.HEADING:` Settings +- `ACCOUNT.SETTINGS.THEME:` Theme +- `ACCOUNT.SETTINGS.THEME_OPTIONS.AUTO:` Auto +- `ACCOUNT.SETTINGS.THEME_OPTIONS.DARK:` Dark +- `ACCOUNT.SETTINGS.THEME_OPTIONS.LIGHT:` Light +- `LEGAL.ABOUT:` About +- `LEGAL.IMPRINT:` Corporate Information +- `LEGAL.PRIVACY_POLICY:` Privacy Notice +- `LEGAL.VERSION:` Version `{{version}}`
#### Don'ts -- `"ABOUT":` "About", -- `"AUTO":` "Auto", -- `"CANCEL":` "Cancel", -- `"DARK":` "Dark", -- `"IMPRINT":` "Corporate Information", -- `"LIGHT":` "Light", -- `"LOG_OUT_NOW":` "Log out now?", -- `"LOGGING_OUT":` "Logging out…", -- `"LOGOUT":` "Log out", -- `"PRIVACY_POLICY":` "Privacy Notice", -- `"SETTINGS":` "Settings", -- `"THEME":` "Theme", -- `"VERSION":` "Version {{version}}" +- `ABOUT:` About +- `AUTO:` Auto +- `CANCEL:` Cancel +- `DARK:` Dark +- `IMPRINT:` Corporate Information +- `LIGHT:` Light +- `LOG_OUT_NOW:` Log out now? +- `LOGGING_OUT:` Logging out… +- `LOGOUT:` Log out +- `PRIVACY_POLICY:` Privacy Notice +- `SETTINGS:` Settings +- `THEME:` Theme +- `VERSION:` Version `{{version}}`
### Reuse strings -Before writing a new string, check whether one with the exact meaning already exists. +Before writing a new string, check whether one with the exact same meaning already exists. Reusing strings… - …reduces the volume sent to translators and lowers cost. -- …gains efficiency. +- …increases the efficiency of product development and maintenance. - …keeps translation unique in every supported language. - …supports the `ONE Tech company` initiative. - +- …helps identifying duplicated functionality. !!! warning "Context-dependent strings" A single string reused across different contexts may require different translations in different languages. @@ -155,18 +149,18 @@ Reusing strings… ### Use translation libraries -[Unicode CLDR](https://cldr.unicode.org/) provides high quality translations for: +Packages based on the [Unicode CLDR](https://cldr.unicode.org/) like `@angular/common` and built-in runtime objects like `Intl` provide complete and high quality translations for: - language and script names - countries and regions - currencies - months, weekdays and time zones -Use these sources to avoid superfluous translate effort. +Use these sources to avoid superfluous translation efforts. ### Provide user-friendly language selection -Provide the languages in the target language for the language switcher. +Provide each language name in the target language for the language switcher.
@@ -223,9 +217,9 @@ Keep sentences as one unit with placeholders. -### Define understandable placeholders +### Define named placeholders -Keep sentence understandable even with placeholders. +Keep sentences understandable even with placeholders.
@@ -255,7 +249,7 @@ Use locale-aware formatting (see [Code tab](#code)), and avoid UX writing depend #### Dos -- Use localization framework (see [Code tab](#code)) +- Use the localization framework (see [Code tab](#code)) - Use [placeholders](#define-understandable-placeholders) in text: `Saved on {date}`
@@ -264,7 +258,7 @@ Use locale-aware formatting (see [Code tab](#code)), and avoid UX writing depend #### Don'ts - `02/03/2026` (ambiguous) -- `1,234.56` everywhere +- `1,234` in all languages (ambiguous, is it less or greater than 2?)
@@ -273,20 +267,23 @@ Use locale-aware formatting (see [Code tab](#code)), and avoid UX writing depend ### Pluralization -The correct translation of texts which relate to a count differs in different languages. +Strings containing numbers may be represented differently in different languages. + +!!! info "Pluralization examples" -Pluralization of the `English` term «apple»: + Pluralization of the `English` term «apple»: -- 1: «I own one apple.» -- n: «I own four apples.» + - 0: «I own no apple.» + - 1: «I own one apple.» + - n: «I own four apples.» -Pluralization of the `Polish` term «Plik» (`English`: «file»): + Pluralization of the `Polish` term «Plik» (`English`: «file»): -- 1 plik -- 2, 3, 4 pliki -- 5-21 plików -- 22-24 pliki -- 25-31 plików + - 1 plik + - 2, 3, 4 pliki + - 5-21 plików + - 22-24 pliki + - 25-31 plików #### Handling of zero From d467820160d8f1ff8d914c1e4480b025f1cf17cd Mon Sep 17 00:00:00 2001 From: Sandro Danioth Date: Wed, 4 Mar 2026 21:17:37 +0100 Subject: [PATCH 07/21] chore(localization): fix formating issues --- docs/fundamentals/localization.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/fundamentals/localization.md b/docs/fundamentals/localization.md index d250d2f97c..d003ec4847 100644 --- a/docs/fundamentals/localization.md +++ b/docs/fundamentals/localization.md @@ -141,15 +141,15 @@ Reusing strings… - …keeps translation unique in every supported language. - …supports the `ONE Tech company` initiative. - …helps identifying duplicated functionality. -!!! warning "Context-dependent strings" + !!! warning "Context-dependent strings" - A single string reused across different contexts may require different translations in different languages. + A single string reused across different contexts may require different translations in different languages. - In doubt, create a separate string for each use even if the English text looks the same. + In doubt, create a separate string for each use even if the English text looks the same. ### Use translation libraries -Packages based on the [Unicode CLDR](https://cldr.unicode.org/) like `@angular/common` and built-in runtime objects like `Intl` provide complete and high quality translations for: +Packages based on the [Unicode CLDR](https://cldr.unicode.org/) like `@angular/common` and built-in runtime objects like `Intl` provide complete and high quality translations for: - language and script names - countries and regions From 974cdad3ac1660e80536e82a150b64cea1cd9ffd Mon Sep 17 00:00:00 2001 From: Sandro Danioth Date: Wed, 4 Mar 2026 22:16:52 +0100 Subject: [PATCH 08/21] chore(localization): incorporate feedback from Lukas May --- docs/fundamentals/localization.md | 41 +++++++++---------------------- 1 file changed, 11 insertions(+), 30 deletions(-) diff --git a/docs/fundamentals/localization.md b/docs/fundamentals/localization.md index d003ec4847..124d16f66a 100644 --- a/docs/fundamentals/localization.md +++ b/docs/fundamentals/localization.md @@ -19,11 +19,11 @@ Localization (l10n) or internationalization (i18n) is the process of designing a -Localization is mainly a [development task](#code) but UX writers can support developers. +UX writers can support [implementation of localization](#code) by understanding, applying, and sharing the following concepts with developers. -User interface texts are stand-alone, short and to the point, but without context. Thus, AI can produce a reliable translation only, the terms must be +User interface texts are stand-alone, short and to the point, but without context. Thus, translators and AI can produce a reliable translation only, the terms must be - [Dominant](#terms-in-various-uses) - [Precise](#terminology) @@ -40,7 +40,7 @@ UX writing combines terminology, [style](ux-text-style-guide/index.md) and form #### Dos - - `Delete template for tool instance IDs` + - `Delete the template for tool instance IDs`
@@ -84,6 +84,7 @@ The ambiguity can be removed by - grouping the texts into namespaces by use cases - only using the [dominant meaning](#terms-in-various-uses) of the term +- annotating texts with a description (if supported by translation framework and file format) #### Grouping of texts @@ -139,13 +140,13 @@ Reusing strings… - …reduces the volume sent to translators and lowers cost. - …increases the efficiency of product development and maintenance. - …keeps translation unique in every supported language. -- …supports the `ONE Tech company` initiative. - …helps identifying duplicated functionality. - !!! warning "Context-dependent strings" - A single string reused across different contexts may require different translations in different languages. +!!! warning "Context-dependent strings" - In doubt, create a separate string for each use even if the English text looks the same. + A single string reused across different contexts may require different translations in different languages. + + In doubt, create a separate string for each use even if the English text looks the same. ### Use translation libraries @@ -285,27 +286,6 @@ Strings containing numbers may be represented differently in different languages - 22-24 pliki - 25-31 plików -#### Handling of zero - -The count 0 is handled differently in several languages. - -
-
- -#### Dos - -- Ich besitze keinen Apfel. («Apfel» | `EN`: «apple» in singular) - -
-
- -#### Don'ts - -- Ich besitze 0 Äpfel («Äpfel» | `EN`: «apples» in plural) - -
-
- #### Linguistic rules Depending on the language there might be up to 6 forms. Following language specific variability does exist: @@ -334,14 +314,15 @@ Pluralization cannot be handled by product code or writing style. Use localizati #### Dos -- `{count} rows` +- `Delete {count} rows?` +- `Delete {rowName}?`
#### Don'ts -- `{count} row(s)` +- `Delete {count} row(s)?` - if (count == 1) {`1 row`} else {`{count} rows`}
From 7d93272c45196b0b1fe5017afe382b1e014f98d6 Mon Sep 17 00:00:00 2001 From: Sandro Danioth Date: Thu, 5 Mar 2026 22:20:51 +0100 Subject: [PATCH 09/21] docs(localization): implement several inputs Add examples for terminology Add sentence about changing reused strings Add chapter about space management Remove One Tech Company initiative Remove Dos and Don'ts subheadings --- docs/fundamentals/localization.md | 178 ++++++++++++++++++++---------- 1 file changed, 121 insertions(+), 57 deletions(-) diff --git a/docs/fundamentals/localization.md b/docs/fundamentals/localization.md index 124d16f66a..b009450ee9 100644 --- a/docs/fundamentals/localization.md +++ b/docs/fundamentals/localization.md @@ -38,15 +38,11 @@ UX writing combines terminology, [style](ux-text-style-guide/index.md) and form
- #### Dos - - `Delete the template for tool instance IDs`
- #### Don'ts - - `Delete complete tool instance ID naming`Deleting a tool instance?
Naming something?
Is "complete" an adjective or a verb?
@@ -74,7 +70,39 @@ Common language serves multiple purposes: Many terms have various meanings related to a specific context or domain. -_One meaning always dominates_ regardless of context. That is the meaning that can be used without creating confusion. However, if that meaning does not fit the context, an alternative term (unambiguous synonym) must be used to eliminate misunderstandings +!!! info "Meaning of the term `title`" + + A subset of meanings of `title` (incl. dominating meaning :trophy:): + + - **1 b:** a similar distinguishing name of a musical composition or a work of art + - **3:** :trophy: descriptive name : [appellation](https://www.merriam-webster.com/dictionary/appellation) + - **4 a:** :trophy: an appellation of dignity, honor, distinction, or preeminence attached to a person or family by virtue of rank, office, precedent, privilege, attainment, or lands + - **4 b:** :trophy: a person holding a title especially of nobility + - **6 c:** all the elements constituting legal ownership + - **7 a:** a descriptive or general heading (as of a chapter in a book) + + See [Merriam Webster](https://www.merriam-webster.com/dictionary/title) for details + +_One meaning always dominates_ regardless of context. That is the meaning that can be used without creating confusion. However, if that meaning does not fit the context, an alternative term (unambiguous synonym) must be used to eliminate misunderstandings. + +
+
+ +- Academic title +- Heading +- Name +- Ownership + +
+
+ +- Title (professor, doctor xyz) +- Title of a book (War and peace) +- Title of an object (Intelligent Valve) +- Title to an asset (Owned by Mr./Ms. xyz) + +
+
In addition, the alternative term substantially increases the probability of correct interpretation by artificial intelligence (as part of translation, machine learning, or any other use). @@ -93,8 +121,6 @@ Group texts by use case and provide meaningful (key) names.
-#### Dos - - `ACCOUNT.LOGOUT.CANCEL:` Cancel - `ACCOUNT.LOGOUT.HEADING:` Log out - `ACCOUNT.LOGOUT.LOG_OUT_NOW:` Log out now? @@ -112,8 +138,6 @@ Group texts by use case and provide meaningful (key) names.
-#### Don'ts - - `ABOUT:` About - `AUTO:` Auto - `CANCEL:` Cancel @@ -131,6 +155,61 @@ Group texts by use case and provide meaningful (key) names.
+### Manage space for translations + +Consider how text will appear in different languages when designing user interfaces. + +1. Design UI by prioritizing flexible layouts, identify areas with limited text space, and always allocate more space than you think you'll need. +1. Write English strings, keeping conciseness in mind from the start. +1. Determine reasonable limits and provide it to the translation management. +1. Request translations +1. Test every screen with translated texts + +!!! warning "UI refactoring" + + Revisit the UI design or the original string if a translator cannot convey the meaning within the limit. + + Fixing UI issues caused by long translations late in the development cycle is expensive and time-consuming. + +#### Awareness for length increase + +Always design with translation in mind, assuming text will grow. + +- Layout breakage + Fixed-width elements may not accommodate longer text, which can result in overflows, line breaks in awkward places, or text disappearing completely. +- Truncation + If text is truncated, important instructions or information may be invisible, which can lead to frustration and misuse. +- UI inconsistency + Different languages require different amounts of space, which makes it difficult to maintain a consistent look and feel. + +#### Required space for translation + +The exact length of a translation cannot be predicted. +Some generally accepted rules of thumb: + +- Short strings (1-10 characters) + These can often increase by 200-300%. (E.g., `EN:`"On" → `DE:`"Eingeschaltet") +- Medium Strings (11-20 characters) + Expect an increase of 100-200%. (E.g., `EN:`"Withdraw request" → `DE:`"Anfrage zurückziehen") +- Longer Strings (21-50 characters) + Expect an increase of 50-100%. +- Very Long Strings (50+ characters) + Depending on the conciseness of the language, the paragraphs can be 30-50% longer, but sometimes also shorter than the original. + +Consider worst case languages: German, Finnish, Greek, and some Slavic languages are known for their long translations. + +!!! tip "Provide translation limits to the translation management tool" + + Set text limits on elements with truly constrained space. + + - Buttons + - Tab labels + - Navigation menu items + - Table headers + - Input field labels + + Texts can be limited by `Character count` or `Pixel width`. + ### Reuse strings Before writing a new string, check whether one with the exact same meaning already exists. @@ -142,6 +221,9 @@ Reusing strings… - …keeps translation unique in every supported language. - …helps identifying duplicated functionality. +However, be careful when changing approved, reused strings to ensure that their meaning is preserved. +If necessary, introduce a new string. + !!! warning "Context-dependent strings" A single string reused across different contexts may require different translations in different languages. @@ -159,37 +241,6 @@ Packages based on the [Unicode CLDR](https://cldr.unicode.org/) like `@angular/c Use these sources to avoid superfluous translation efforts. -### Provide user-friendly language selection - -Provide each language name in the target language for the language switcher. - -
-
- -#### Dos - -- English -- Deutsch -- Français -- Italiano -- Ελληνικά -- 中文 - -
-
- -#### Don'ts - -- 英语 -- 德语 -- 法语 -- 意大利语 -- 希腊 -- 中文 - -
-
- ### Avoid string concatenations Building sentences from fragments prevents correct grammar in many languages. @@ -200,16 +251,12 @@ Keep sentences as one unit with placeholders.
-#### Dos - - EN: `Select site {site} of {company}?` - DE: `Standort {site} von {company} auswählen?`
-#### Don'ts - - EN: `Select site ` + `{site}` + `of` + `{company}` + `?` - DE: `Standort auswählen ` + `{site}` + `von` + `{company}` + `?` @@ -218,6 +265,8 @@ Keep sentences as one unit with placeholders. +The verb (`EN:`"select" / `DE:`"auswählen") is at the begin of the sentence in English but at the end in German. + ### Define named placeholders Keep sentences understandable even with placeholders. @@ -225,15 +274,11 @@ Keep sentences understandable even with placeholders.
-#### Dos - - `Reactivating site {name} within activation period: {startDate} – {endDate}`
-#### Don'ts - - `Reactivating site {1} within activation period: {2} – {3}`
@@ -248,18 +293,14 @@ Use locale-aware formatting (see [Code tab](#code)), and avoid UX writing depend
-#### Dos - - Use the localization framework (see [Code tab](#code)) - Use [placeholders](#define-understandable-placeholders) in text: `Saved on {date}`
-#### Don'ts - - `02/03/2026` (ambiguous) -- `1,234` in all languages (ambiguous, is it less or greater than 2?) +- `1,234` in all languages (ambiguous, less or greater than 2?)
@@ -312,22 +353,45 @@ Pluralization cannot be handled by product code or writing style. Use localizati
-#### Dos - - `Delete {count} rows?` - `Delete {rowName}?`
-#### Don'ts - - `Delete {count} row(s)?` - if (count == 1) {`1 row`} else {`{count} rows`}
+### Provide user-friendly language selection + +Provide each language name in the target language for the language switcher. + +
+
+ +- English +- Deutsch +- Français +- Italiano +- Ελληνικά +- 中文 + +
+
+ +- 英语 +- 德语 +- 法语 +- 意大利语 +- 希腊 +- 中文 + +
+
+ ## Code --- Angular supports localization as described in the [i18n](https://angular.dev/guide/i18n) guide and is supported by [pipes](https://angular.dev/guide/templates/pipes). From 7cbf9030586e4150d06f10eabc810d1f440fb0f6 Mon Sep 17 00:00:00 2001 From: Sandro Danioth Date: Fri, 6 Mar 2026 11:58:23 +0100 Subject: [PATCH 10/21] chore(localization): fix spelling mistake --- docs/fundamentals/localization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fundamentals/localization.md b/docs/fundamentals/localization.md index b009450ee9..3f109b1beb 100644 --- a/docs/fundamentals/localization.md +++ b/docs/fundamentals/localization.md @@ -265,7 +265,7 @@ Keep sentences as one unit with placeholders. -The verb (`EN:`"select" / `DE:`"auswählen") is at the begin of the sentence in English but at the end in German. +The verb (`EN:`"select" / `DE:`"auswählen") is at the beginning of the sentence in English but at the end in German. ### Define named placeholders From 1e971e3baaa0b21021a0873e50900530d04c58cf Mon Sep 17 00:00:00 2001 From: Sandro Danioth Date: Fri, 6 Mar 2026 13:37:39 +0100 Subject: [PATCH 11/21] chore(localization): fine-tuning based on feedback for Michael Co-authored-by: michael-smt <139211597+michael-smt@users.noreply.github.com> --- docs/fundamentals/localization.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/fundamentals/localization.md b/docs/fundamentals/localization.md index 3f109b1beb..1f500824e7 100644 --- a/docs/fundamentals/localization.md +++ b/docs/fundamentals/localization.md @@ -23,7 +23,7 @@ UX writers can support [implementation of localization](#code) by understanding, -User interface texts are stand-alone, short and to the point, but without context. Thus, translators and AI can produce a reliable translation only, the terms must be +User interface texts are stand-alone, short, and to the point, but they provide little to no context on their own. Thus, translators and AI can only produce a reliable translation if the terms are - [Dominant](#terms-in-various-uses) - [Precise](#terminology) @@ -74,16 +74,16 @@ Many terms have various meanings related to a specific context or domain. A subset of meanings of `title` (incl. dominating meaning :trophy:): - - **1 b:** a similar distinguishing name of a musical composition or a work of art - - **3:** :trophy: descriptive name : [appellation](https://www.merriam-webster.com/dictionary/appellation) - - **4 a:** :trophy: an appellation of dignity, honor, distinction, or preeminence attached to a person or family by virtue of rank, office, precedent, privilege, attainment, or lands - - **4 b:** :trophy: a person holding a title especially of nobility - - **6 c:** all the elements constituting legal ownership - - **7 a:** a descriptive or general heading (as of a chapter in a book) + - a similar distinguishing name of a musical composition or a work of art + - :trophy: descriptive name : [appellation](https://www.merriam-webster.com/dictionary/appellation) + - :trophy: an appellation of dignity, honor, distinction, or preeminence attached to a person or family by virtue of rank, office, precedent, privilege, attainment, or lands + - :trophy: a person holding a title especially of nobility + - all the elements constituting legal ownership + - a descriptive or general heading (as of a chapter in a book) See [Merriam Webster](https://www.merriam-webster.com/dictionary/title) for details -_One meaning always dominates_ regardless of context. That is the meaning that can be used without creating confusion. However, if that meaning does not fit the context, an alternative term (unambiguous synonym) must be used to eliminate misunderstandings. +_One meaning always dominates_ regardless of context. That is the meaning that can be used without creating confusion. However, if this dominating meaning does not fit the context, an alternative term (unambiguous synonym) must be used to eliminate misunderstandings.
From 699ef87d4cb17987f51e0bf5cd1130b116f08121 Mon Sep 17 00:00:00 2001 From: Sandro Danioth Date: Thu, 12 Mar 2026 13:29:20 +0100 Subject: [PATCH 12/21] docs(localization): incorporate feedback from Jennie 1 Added a glossary Rephrased the sub-heading Removed 1. box Added a section about RTL/LTR Removed italic and bold styles --- docs/fundamentals/localization.md | 70 +++++++++++++++++++++++++------ 1 file changed, 58 insertions(+), 12 deletions(-) diff --git a/docs/fundamentals/localization.md b/docs/fundamentals/localization.md index 1f500824e7..6e2f17832c 100644 --- a/docs/fundamentals/localization.md +++ b/docs/fundamentals/localization.md @@ -2,19 +2,42 @@ # Localization -Localization (l10n) or internationalization (i18n) is the process of designing and implementing a product for a **specific language and region**. +Internationalization (i18n) is the process of designing and developing a product for localization (l10n) into specific languages and regions. ## Introduction --- -!!! tip "Localization is more than just translating text" +### Internationalization (i18n) - - It covers translation, but also **formats** (date/time/number), **script direction** (LTR/RTL), and UI behavior in different languages. - - Depending on how it is used, the **same English word** can have multiple meanings and translates to different words in another language. - - Languages differ in **word order**, **plural rules**, and **punctuation**. - - UI text can **grow** (sometimes a lot), wrap, or break layouts. +Internationalization is the entire process of designing and developing a product that can be adapted to different languages and regions. +Internationalization is the foundation for high-quality and efficient [localization](#localization-l10n). + +It is important to consider that UI text can grow significantly and thus cause line breaks or destroy the layout. + +### Localization (l10n) + +Localization is the process of adapting a product to the language and cultural norms of a specific target market so that it feels natural to local users. This goes beyond [simple translation](#translation) and includes script direction ([LTR](#ltr-left-to-right)/[RTL](#rtl-right-to-left)), formatting numbers, times, dates, and addresses, and adapting illustrations. +Localization requires an [internationalized](#internationalization-i18n) product and must be performed for each target market. + +### Translation + +Translation is the central linguistic component of [localization](#localization-l10n), whereby the tone must be adapted to local requirements and the meaning must be conveyed accurately. + +It is important to consider that languages differ in terms of word order, plural rules, and punctuation. +In addition, an English word can have multiple meanings and be translated into other languages using different words. + +### LTR (Left-to-Right) + +LTR refers to languages (e.g., English, German, French, Spanish) and scripts that are written and read from left to right. + +### RTL (Right-to-Left) + +RTL refers to languages (e.g., Arabic, Hebrew, Persian) and writing systems that are written and read from right to left. + +It is important to consider that often the entire user interface must be mirrored, which imposes significant demands on [internationalization](#internationalization-i18n). + ## UX Writing --- @@ -33,7 +56,7 @@ UX writing combines terminology, [style](ux-text-style-guide/index.md) and form !!! tip "Think like a translator" - Every string will be translated without access to the surrounding UI. Ask yourself: is this text understandable **without visual context**? + Every string will be translated without access to the surrounding UI. Ask yourself: is this text understandable without visual context?
@@ -56,10 +79,10 @@ UX writing combines terminology, [style](ux-text-style-guide/index.md) and form Common language serves multiple purposes: -- _Clarity of communication_, common understanding between people and companies -- _Applicability_ across multiple systems/tools/hardware… -- _Openness_ to third parties, breaking up of silos -- Foundation for _artificial intelligence_ +- Clarity of communication, common understanding between people and companies +- Applicability across multiple systems/tools/hardware… +- Openness to third parties, breaking up of silos +- Foundation for artificial intelligence !!! warning "Usage of terminology databases" @@ -83,7 +106,7 @@ Many terms have various meanings related to a specific context or domain. See [Merriam Webster](https://www.merriam-webster.com/dictionary/title) for details -_One meaning always dominates_ regardless of context. That is the meaning that can be used without creating confusion. However, if this dominating meaning does not fit the context, an alternative term (unambiguous synonym) must be used to eliminate misunderstandings. +One meaning always dominates regardless of context. That is the meaning that can be used without creating confusion. However, if this dominating meaning does not fit the context, an alternative term (unambiguous synonym) must be used to eliminate misunderstandings.
@@ -241,6 +264,29 @@ Packages based on the [Unicode CLDR](https://cldr.unicode.org/) like `@angular/c Use these sources to avoid superfluous translation efforts. +### Avoid directional terms on UI + +Directional terms might get incorrect if the user interface is mirrored for [RTL languages](#rtl-right-to-left). + + + +
+
+ +- Site pane +- Vertical navigation + +
+
+ +- Right pane +- Left navigation + +
+
+ + + ### Avoid string concatenations Building sentences from fragments prevents correct grammar in many languages. From 28524585b3ab7ac0432f68fab99f3187ecb37cf7 Mon Sep 17 00:00:00 2001 From: Sandro Danioth Date: Thu, 12 Mar 2026 18:17:47 +0100 Subject: [PATCH 13/21] docs(localization): apply 2nd bundle of changes based on Jennies feedback Co-authored-by: Sandro Danioth --- docs/fundamentals/localization.md | 22 ++++++++++++++-------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/docs/fundamentals/localization.md b/docs/fundamentals/localization.md index 6e2f17832c..a9df50e9ca 100644 --- a/docs/fundamentals/localization.md +++ b/docs/fundamentals/localization.md @@ -71,11 +71,11 @@ UX writing combines terminology, [style](ux-text-style-guide/index.md) and form
-### Terminology +### Domain terminology - The terms are defined by experts (physicists, engineers, lawyers, etc.) from universities and various global companies specializing in specific domains. -- Standardization bodies (e.g., ISO, EN, UL, BS, DIN, ASHRAE, BACnet) are standardizing common terms. -- Quasi-industrial standards from individual sources (Haystack, Bric etc.) become international standards only if aligned to official organizations. If not aligned, setting a standard remains wishful thinking. +- Standardization bodies (e.g., [ISO](https://iso.org), [EN](https://cen.eu), [UL](https://ul.com), [IEC](https://iec.ch)) are standardizing common terms. +- Avoid terms from quasi-industrial standards until they have been harmonized with official standardization bodies and are generally accepted. Common language serves multiple purposes: @@ -92,6 +92,7 @@ Common language serves multiple purposes: #### Terms in various uses Many terms have various meanings related to a specific context or domain. +Use the terminology database of domain, review the UI texts together with domain experts, and ensure that translations are done by translators with domain knowledge. !!! info "Meaning of the term `title`" @@ -129,9 +130,9 @@ One meaning always dominates regardless of context. That is the meaning that can In addition, the alternative term substantially increases the probability of correct interpretation by artificial intelligence (as part of translation, machine learning, or any other use). -### Remove ambiguity +### Avoid misunderstandings -The ambiguity can be removed by +Avoid possible causes of misunderstandings - grouping the texts into namespaces by use cases - only using the [dominant meaning](#terms-in-various-uses) of the term @@ -139,7 +140,9 @@ The ambiguity can be removed by #### Grouping of texts -Group texts by use case and provide meaningful (key) names. +Translators translate texts individually. +In order to understand the context and maintain consistency, it is necessary to have related texts close together. +Related texts can be brought together by grouping texts based on use cases (e.g., Manage users → Arrow right) along with meaningful (key) names.
@@ -219,7 +222,7 @@ Some generally accepted rules of thumb: - Very Long Strings (50+ characters) Depending on the conciseness of the language, the paragraphs can be 30-50% longer, but sometimes also shorter than the original. -Consider worst case languages: German, Finnish, Greek, and some Slavic languages are known for their long translations. +Consider German, Finnish, Greek, and some Slavic languages, which are known for their long translations. !!! tip "Provide translation limits to the translation management tool" @@ -355,7 +358,8 @@ Use locale-aware formatting (see [Code tab](#code)), and avoid UX writing depend ### Pluralization -Strings containing numbers may be represented differently in different languages. +Each language has its own grammatical rules that specify how texts containing numbers must be presented. +It is important to consider these different rules early in the UX writing and implementation process to ensure that the product can be localized correctly. !!! info "Pluralization examples" @@ -392,6 +396,8 @@ Depending on the language there might be up to 6 forms. Following language speci | 4 | Special case for one and all numbers ending in `02`, `03`, or `04` | Slovenian | | 6 | Special cases for one, two, all numbers ending in `02`, `03`, … `10`, all numbers ending in `11` … `99`, and others | Arabic | +The [plural rules specification from the Unicode CLDR project](https://cldr.unicode.org/index/cldr-spec/plural-rules) contains a detailed linguistic analysis. + #### Use localization to handle pluralization Pluralization cannot be handled by product code or writing style. Use localization (e.g., ICU or framework plural rules) instead. From 8bbe21dcba8913b7d1d5bbc13f32640ca4743c35 Mon Sep 17 00:00:00 2001 From: Sandro Danioth Date: Thu, 12 Mar 2026 23:19:20 +0100 Subject: [PATCH 14/21] docs(localization): implement 3rd package of Jennie's feedback Extended the definition of UX writer in i18n Added & adapted examples Reduced amount of visual elements linter ignore removed --- docs/fundamentals/localization.md | 135 +++++++++++++++++++----------- 1 file changed, 84 insertions(+), 51 deletions(-) diff --git a/docs/fundamentals/localization.md b/docs/fundamentals/localization.md index a9df50e9ca..341a95c6cd 100644 --- a/docs/fundamentals/localization.md +++ b/docs/fundamentals/localization.md @@ -1,4 +1,4 @@ - + # Localization @@ -40,36 +40,37 @@ It is important to consider that often the entire user interface must be mirrore ## UX Writing --- - +UX writers are the text experts in the product development team and therefore ideal ambassadors for internationalization. +They need to be aware of the challenges of localization and understand how they can support UX designers in creating localization-friendly designs (e.g., [space for translation](#manage-space-for-translations)). -UX writers can support [implementation of localization](#code) by understanding, applying, and sharing the following concepts with developers. +In addition, translation-friendly texts should be defined by thinking like a translator: “Is the text understandable without the visual context?” - +
+
-User interface texts are stand-alone, short, and to the point, but they provide little to no context on their own. Thus, translators and AI can only produce a reliable translation if the terms are +- `Delete the template for tool instance IDs` -- [Dominant](#terms-in-various-uses) -- [Precise](#terminology) -- [Unambiguous](#remove-ambiguity) +
+
-UX writing combines terminology, [style](ux-text-style-guide/index.md) and form to ensure a consistent UI for specific use cases of a target audience. +- `Delete complete tool instance ID naming`Deleting a tool instance?
Naming something?
Is "complete" an adjective or a verb? -!!! tip "Think like a translator" +
+
- Every string will be translated without access to the surrounding UI. Ask yourself: is this text understandable without visual context? +User interface texts are stand-alone, short, and to the point, but they provide little to no context on their own. Thus, translators and AI can only produce a reliable translation if the terms are -
-
+- [Dominant](#terms-in-various-uses) +- [Precise](#domain-terminology) +- [Unambiguous](#avoid-misunderstandings) - - `Delete the template for tool instance IDs` +UX writing combines terminology, style and form to ensure a consistent UI for specific use cases of a target audience. -
-
+ - - `Delete complete tool instance ID naming`Deleting a tool instance?
Naming something?
Is "complete" an adjective or a verb? +The handover documentation to development must include the UX writing specifications (e.g., [placeholder names](#define-named-placeholders) or [grouping of texts](#grouping-of-texts)) as a basis for [implementing internationalization](#code). -
-
+ ### Domain terminology @@ -84,15 +85,13 @@ Common language serves multiple purposes: - Openness to third parties, breaking up of silos - Foundation for artificial intelligence -!!! warning "Usage of terminology databases" - - - Select the terminology database of your domain. - - Identify terms not yet defined and request them in the terminology database or by contacting the terminology maintainers of your domain. - #### Terms in various uses Many terms have various meanings related to a specific context or domain. -Use the terminology database of domain, review the UI texts together with domain experts, and ensure that translations are done by translators with domain knowledge. + +Use the terminology database of domain to maintain a common language. +UX writers are asked to request terms from the terminology maintainers of the domain (via the terminology database) if the term is not yet defined. +Review the UI texts together with domain experts, and ensure that translations are done by translators with domain knowledge. !!! info "Meaning of the term `title`" @@ -132,9 +131,9 @@ In addition, the alternative term substantially increases the probability of cor ### Avoid misunderstandings -Avoid possible causes of misunderstandings +Avoid possible causes of misunderstandings by -- grouping the texts into namespaces by use cases +- grouping the texts by use cases - only using the [dominant meaning](#terms-in-various-uses) of the term - annotating texts with a description (if supported by translation framework and file format) @@ -142,7 +141,7 @@ Avoid possible causes of misunderstandings Translators translate texts individually. In order to understand the context and maintain consistency, it is necessary to have related texts close together. -Related texts can be brought together by grouping texts based on use cases (e.g., Manage users → Arrow right) along with meaningful (key) names. +Related texts can be brought together by grouping texts based on use cases (e.g., My account → Theme selection) along with meaningful (key) names.
@@ -183,19 +182,16 @@ Related texts can be brought together by grouping texts based on use cases (e.g. ### Manage space for translations -Consider how text will appear in different languages when designing user interfaces. +Design user interfaces by following these steps to ensure that translations have space in the user interface. 1. Design UI by prioritizing flexible layouts, identify areas with limited text space, and always allocate more space than you think you'll need. 1. Write English strings, keeping conciseness in mind from the start. 1. Determine reasonable limits and provide it to the translation management. 1. Request translations -1. Test every screen with translated texts - -!!! warning "UI refactoring" +1. Test every screen with translated texts + Revisit the UI design or the original string if a translator cannot convey the meaning within the limit. - Revisit the UI design or the original string if a translator cannot convey the meaning within the limit. - - Fixing UI issues caused by long translations late in the development cycle is expensive and time-consuming. +Fixing UI issues caused by long translations late in the development cycle is expensive and time-consuming. #### Awareness for length increase @@ -208,6 +204,8 @@ Always design with translation in mind, assuming text will grow. - UI inconsistency Different languages require different amounts of space, which makes it difficult to maintain a consistent look and feel. +UX writers are ambassadors of internationalization and are asked to support UX designers in creating localization-friendly designs. + #### Required space for translation The exact length of a translation cannot be predicted. @@ -224,37 +222,71 @@ Some generally accepted rules of thumb: Consider German, Finnish, Greek, and some Slavic languages, which are known for their long translations. -!!! tip "Provide translation limits to the translation management tool" +#### Limit space if required + +Identify UI elements which truly offer limited space, even if a flexible design is the preferred choice. +The following UI elements may require text length restrictions: - Set text limits on elements with truly constrained space. +- Buttons +- Tab labels +- Navigation menu items +- Table headers +- Input field labels - - Buttons - - Tab labels - - Navigation menu items - - Table headers - - Input field labels +Texts can be limited by the translation management tool in terms of character count or pixel width. - Texts can be limited by `Character count` or `Pixel width`. +### Reuse texts -### Reuse strings +Before writing a new text, check whether one with the exact same meaning already exists. -Before writing a new string, check whether one with the exact same meaning already exists. +
+
-Reusing strings… +- `COMMON.SAVE:` Save + +
+
+ +- `USERS.EDIT_USER.SAVE:` Save +- `DEVICES.EDIT_DEVICE.SAVE:` Save + +
+
+ +Reusing the same instance of text… - …reduces the volume sent to translators and lowers cost. - …increases the efficiency of product development and maintenance. - …keeps translation unique in every supported language. - …helps identifying duplicated functionality. -However, be careful when changing approved, reused strings to ensure that their meaning is preserved. -If necessary, introduce a new string. +However, be careful when changing approved, reused texts to ensure that their meaning is preserved. + +An English text may require different translations in different contexts. +In such cases, a separate text must be created. + + + +
+
+ +- `COMMON.CANCEL:` "Cancel" for processes only +- Translation to German: "Abbrechen" +- Add `CONTRACT.CANCEL:` "Cancel" for contracts +- Translation to German: "Stornieren" -!!! warning "Context-dependent strings" +
+
- A single string reused across different contexts may require different translations in different languages. +- `CANCEL:` "Cancel" in context of process and contract +- Translation to German: "Abbrechen" or "Stornieren"? + +
+
+ + - In doubt, create a separate string for each use even if the English text looks the same. +If in doubt, create a separate text for each use, even if the English text appears to be identical. ### Use translation libraries @@ -270,6 +302,7 @@ Use these sources to avoid superfluous translation efforts. ### Avoid directional terms on UI Directional terms might get incorrect if the user interface is mirrored for [RTL languages](#rtl-right-to-left). +Use direction agnostic texts instead. From c65bb7cfcdbd855e2968f079a2d091eb4ff3de10 Mon Sep 17 00:00:00 2001 From: Sandro Danioth Date: Thu, 12 Mar 2026 23:34:02 +0100 Subject: [PATCH 15/21] docs(localization): replace term string --- docs/fundamentals/localization.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/fundamentals/localization.md b/docs/fundamentals/localization.md index 341a95c6cd..06badc069f 100644 --- a/docs/fundamentals/localization.md +++ b/docs/fundamentals/localization.md @@ -185,11 +185,11 @@ Related texts can be brought together by grouping texts based on use cases (e.g. Design user interfaces by following these steps to ensure that translations have space in the user interface. 1. Design UI by prioritizing flexible layouts, identify areas with limited text space, and always allocate more space than you think you'll need. -1. Write English strings, keeping conciseness in mind from the start. +1. Write English texts, keeping conciseness in mind from the start. 1. Determine reasonable limits and provide it to the translation management. 1. Request translations 1. Test every screen with translated texts - Revisit the UI design or the original string if a translator cannot convey the meaning within the limit. + Revisit the UI design or the original texts if a translator cannot convey the meaning within the limit. Fixing UI issues caused by long translations late in the development cycle is expensive and time-consuming. @@ -211,13 +211,13 @@ UX writers are ambassadors of internationalization and are asked to support UX d The exact length of a translation cannot be predicted. Some generally accepted rules of thumb: -- Short strings (1-10 characters) +- Short texts (1-10 characters) These can often increase by 200-300%. (E.g., `EN:`"On" → `DE:`"Eingeschaltet") -- Medium Strings (11-20 characters) +- Medium texts (11-20 characters) Expect an increase of 100-200%. (E.g., `EN:`"Withdraw request" → `DE:`"Anfrage zurückziehen") -- Longer Strings (21-50 characters) +- Longer texts (21-50 characters) Expect an increase of 50-100%. -- Very Long Strings (50+ characters) +- Very Long texts (50+ characters) Depending on the conciseness of the language, the paragraphs can be 30-50% longer, but sometimes also shorter than the original. Consider German, Finnish, Greek, and some Slavic languages, which are known for their long translations. @@ -323,7 +323,7 @@ Use direction agnostic texts instead. -### Avoid string concatenations +### Avoid text concatenations Building sentences from fragments prevents correct grammar in many languages. Keep sentences as one unit with placeholders. From 86fa5f52918eb6d00ee4c3ec0c23f77ec02c2573 Mon Sep 17 00:00:00 2001 From: Sandro Danioth Date: Tue, 17 Mar 2026 10:18:08 +0100 Subject: [PATCH 16/21] docs(localization): incorporate feedback from Jennie, Andrea, and Lukas Co-authored-by: Sandro Danioth --- docs/fundamentals/localization.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/docs/fundamentals/localization.md b/docs/fundamentals/localization.md index 06badc069f..16711b2005 100644 --- a/docs/fundamentals/localization.md +++ b/docs/fundamentals/localization.md @@ -11,12 +11,11 @@ Internationalization (i18n) is the process of designing and developing a product Internationalization is the entire process of designing and developing a product that can be adapted to different languages and regions. Internationalization is the foundation for high-quality and efficient [localization](#localization-l10n). -It is important to consider that UI text can grow significantly and thus cause line breaks or destroy the layout. - ### Localization (l10n) Localization is the process of adapting a product to the language and cultural norms of a specific target market so that it feels natural to local users. This goes beyond [simple translation](#translation) and includes script direction ([LTR](#ltr-left-to-right)/[RTL](#rtl-right-to-left)), formatting numbers, times, dates, and addresses, and adapting illustrations. +This example shows how values, dates, and times should be displayed after the product has been localized. Localization requires an [internationalized](#internationalization-i18n) product and must be performed for each target market. @@ -60,7 +59,7 @@ In addition, translation-friendly texts should be defined by thinking like a tra User interface texts are stand-alone, short, and to the point, but they provide little to no context on their own. Thus, translators and AI can only produce a reliable translation if the terms are -- [Dominant](#terms-in-various-uses) +- [Predominant](#terms-in-various-uses) - [Precise](#domain-terminology) - [Unambiguous](#avoid-misunderstandings) @@ -95,12 +94,12 @@ Review the UI texts together with domain experts, and ensure that translations a !!! info "Meaning of the term `title`" - A subset of meanings of `title` (incl. dominating meaning :trophy:): + A subset of meanings of `title`: + - predominant meaning: an appellation of dignity, honor, distinction, or preeminence attached to a person or family by virtue of rank, office, precedent, privilege, attainment, or lands + - descriptive name : [appellation](https://www.merriam-webster.com/dictionary/appellation) + - a person holding a title especially of nobility - a similar distinguishing name of a musical composition or a work of art - - :trophy: descriptive name : [appellation](https://www.merriam-webster.com/dictionary/appellation) - - :trophy: an appellation of dignity, honor, distinction, or preeminence attached to a person or family by virtue of rank, office, precedent, privilege, attainment, or lands - - :trophy: a person holding a title especially of nobility - all the elements constituting legal ownership - a descriptive or general heading (as of a chapter in a book) @@ -134,7 +133,7 @@ In addition, the alternative term substantially increases the probability of cor Avoid possible causes of misunderstandings by - grouping the texts by use cases -- only using the [dominant meaning](#terms-in-various-uses) of the term +- only using the [predominant meaning](#terms-in-various-uses) of the term - annotating texts with a description (if supported by translation framework and file format) #### Grouping of texts From 0a53de54293106e9a8b9a7a08746603c535e0686 Mon Sep 17 00:00:00 2001 From: Sandro Danioth Date: Fri, 20 Mar 2026 13:24:04 +0100 Subject: [PATCH 17/21] docs(localization): reduce usage of abbreviations i18n and l10n --- docs/fundamentals/localization.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/fundamentals/localization.md b/docs/fundamentals/localization.md index 16711b2005..5e6fe5050c 100644 --- a/docs/fundamentals/localization.md +++ b/docs/fundamentals/localization.md @@ -2,18 +2,18 @@ # Localization -Internationalization (i18n) is the process of designing and developing a product for localization (l10n) into specific languages and regions. +Internationalization is the process of designing and developing a product for localization into specific languages and regions. ## Introduction --- ### Internationalization (i18n) -Internationalization is the entire process of designing and developing a product that can be adapted to different languages and regions. +Internationalization (sometimes abbreviated as i18n) is the entire process of designing and developing a product that can be adapted to different languages and regions. Internationalization is the foundation for high-quality and efficient [localization](#localization-l10n). ### Localization (l10n) -Localization is the process of adapting a product to the language and cultural norms of a specific target market so that it feels natural to local users. This goes beyond [simple translation](#translation) and includes script direction ([LTR](#ltr-left-to-right)/[RTL](#rtl-right-to-left)), formatting numbers, times, dates, and addresses, and adapting illustrations. +Localization (sometimes abbreviated as l10n) is the process of adapting a product to the language and cultural norms of a specific target market so that it feels natural to local users. This goes beyond [simple translation](#translation) and includes script direction ([LTR](#ltr-left-to-right)/[RTL](#rtl-right-to-left)), formatting numbers, times, dates, and addresses, and adapting illustrations. This example shows how values, dates, and times should be displayed after the product has been localized. @@ -478,7 +478,7 @@ Provide each language name in the target language for the language switcher. ## Code --- -Angular supports localization as described in the [i18n](https://angular.dev/guide/i18n) guide and is supported by [pipes](https://angular.dev/guide/templates/pipes). +Angular supports localization as described in the [Angular Internationalization (i18n)](https://angular.dev/guide/i18n) guide and is supported by [pipes](https://angular.dev/guide/templates/pipes). Angular applies a compile time localization concept. It does not support the change of locales (language and formats) at runtime. Instead, for each locale it generates a new web application that supports exactly one locale. It replaces text in the HTML templates with the translations and sets a fixed [LOCALE_ID](https://angular.dev/guide/i18n/locale-id) which is used by the pipes. Changing locales is realized by changing the web application. From dc79b0a9537fab8a607b5f9d08791f5846497144 Mon Sep 17 00:00:00 2001 From: Sandro Danioth Date: Tue, 24 Mar 2026 09:58:33 +0100 Subject: [PATCH 18/21] docs(localization): incorporate feedback of Jennie Co-authored-by: tokyojen <143795032+tokyojen@users.noreply.github.com> Co-authored-by: Sandro Danioth --- docs/fundamentals/localization.md | 46 +++++++++++++++++-------------- 1 file changed, 25 insertions(+), 21 deletions(-) diff --git a/docs/fundamentals/localization.md b/docs/fundamentals/localization.md index 5e6fe5050c..557b3774c2 100644 --- a/docs/fundamentals/localization.md +++ b/docs/fundamentals/localization.md @@ -9,21 +9,21 @@ Internationalization is the process of designing and developing a product for lo ### Internationalization (i18n) Internationalization (sometimes abbreviated as i18n) is the entire process of designing and developing a product that can be adapted to different languages and regions. -Internationalization is the foundation for high-quality and efficient [localization](#localization-l10n). +It is the foundation for high-quality and efficient [localization](#localization-l10n). ### Localization (l10n) Localization (sometimes abbreviated as l10n) is the process of adapting a product to the language and cultural norms of a specific target market so that it feels natural to local users. This goes beyond [simple translation](#translation) and includes script direction ([LTR](#ltr-left-to-right)/[RTL](#rtl-right-to-left)), formatting numbers, times, dates, and addresses, and adapting illustrations. +Localization requires an [internationalized](#internationalization-i18n) product and must be performed for each target market. + +#### Localization example This example shows how values, dates, and times should be displayed after the product has been localized. -Localization requires an [internationalized](#internationalization-i18n) product and must be performed for each target market. - ### Translation Translation is the central linguistic component of [localization](#localization-l10n), whereby the tone must be adapted to local requirements and the meaning must be conveyed accurately. - It is important to consider that languages differ in terms of word order, plural rules, and punctuation. In addition, an English word can have multiple meanings and be translated into other languages using different words. @@ -35,14 +35,17 @@ LTR refers to languages (e.g., English, German, French, Spanish) and scripts tha RTL refers to languages (e.g., Arabic, Hebrew, Persian) and writing systems that are written and read from right to left. -It is important to consider that often the entire user interface must be mirrored, which imposes significant demands on [internationalization](#internationalization-i18n). +Because of these differences, it's important for UX writers to consider that often the entire user interface must be mirrored, which imposes significant demands on [internationalization](#internationalization-i18n). ## UX Writing --- UX writers are the text experts in the product development team and therefore ideal ambassadors for internationalization. They need to be aware of the challenges of localization and understand how they can support UX designers in creating localization-friendly designs (e.g., [space for translation](#manage-space-for-translations)). +This page gives recommendations on how UX writers can support localization teams and translators to minimize internationalization challenges. + +### Consider translation -In addition, translation-friendly texts should be defined by thinking like a translator: “Is the text understandable without the visual context?” +Translation-friendly texts should be created by UX writers thinking like a translator and asking the question: “Is the text understandable without the visual context?”.
@@ -67,30 +70,31 @@ UX writing combines terminology, style and form to ensure a consistent UI for sp +### Handover UX writing specifications + The handover documentation to development must include the UX writing specifications (e.g., [placeholder names](#define-named-placeholders) or [grouping of texts](#grouping-of-texts)) as a basis for [implementing internationalization](#code). -### Domain terminology +### Use domain terminology - The terms are defined by experts (physicists, engineers, lawyers, etc.) from universities and various global companies specializing in specific domains. -- Standardization bodies (e.g., [ISO](https://iso.org), [EN](https://cen.eu), [UL](https://ul.com), [IEC](https://iec.ch)) are standardizing common terms. -- Avoid terms from quasi-industrial standards until they have been harmonized with official standardization bodies and are generally accepted. +- Standardization bodies (e.g., [ISO](https://iso.org), [EN](https://cen.eu), [UL](https://ul.com), [IEC](https://iec.ch)) are the people responsible for standardizing common terms. +- UX writers should avoid terms from quasi-industrial standards until they have been harmonized with official standardization bodies and are generally accepted. Common language serves multiple purposes: - Clarity of communication, common understanding between people and companies -- Applicability across multiple systems/tools/hardware… +- Applicability across multiple systems/tools/hardware, etc. - Openness to third parties, breaking up of silos - Foundation for artificial intelligence #### Terms in various uses Many terms have various meanings related to a specific context or domain. - Use the terminology database of domain to maintain a common language. -UX writers are asked to request terms from the terminology maintainers of the domain (via the terminology database) if the term is not yet defined. -Review the UI texts together with domain experts, and ensure that translations are done by translators with domain knowledge. +UX writers should request terms from the terminology maintainers of the domain if the term is not yet defined (via terminology databases if available). +Then UX writers should review the UI texts together with domain experts, and ensure that translations are done by translators with domain knowledge. !!! info "Meaning of the term `title`" @@ -136,7 +140,7 @@ Avoid possible causes of misunderstandings by - only using the [predominant meaning](#terms-in-various-uses) of the term - annotating texts with a description (if supported by translation framework and file format) -#### Grouping of texts +#### Group texts Translators translate texts individually. In order to understand the context and maintain consistency, it is necessary to have related texts close together. @@ -205,7 +209,7 @@ Always design with translation in mind, assuming text will grow. UX writers are ambassadors of internationalization and are asked to support UX designers in creating localization-friendly designs. -#### Required space for translation +#### Make space for translation The exact length of a translation cannot be predicted. Some generally accepted rules of thumb: @@ -252,7 +256,7 @@ Before writing a new text, check whether one with the exact same meaning already
-Reusing the same instance of text… +Reusing the same instance of text has the following advantages: - …reduces the volume sent to translators and lowers cost. - …increases the efficiency of product development and maintenance. @@ -300,7 +304,7 @@ Use these sources to avoid superfluous translation efforts. ### Avoid directional terms on UI -Directional terms might get incorrect if the user interface is mirrored for [RTL languages](#rtl-right-to-left). +Directional terms might be incorrect if the user interface is mirrored for [RTL languages](#rtl-right-to-left). Use direction agnostic texts instead. @@ -346,7 +350,7 @@ Keep sentences as one unit with placeholders. -The verb (`EN:`"select" / `DE:`"auswählen") is at the beginning of the sentence in English but at the end in German. +Note: The verb (`EN:`"select" / `DE:`"auswählen") is at the beginning of the sentence in English but at the end in German. ### Define named placeholders @@ -409,9 +413,9 @@ It is important to consider these different rules early in the UX writing and im - 22-24 pliki - 25-31 plików -#### Linguistic rules +#### Consider different linguistic rules -Depending on the language there might be up to 6 forms. Following language specific variability does exist: +Depending on the language there might be up to 6 forms. The following language specific variability exists: | Forms | Grammatical rules | Languages | | :---: | ------------------------------------------------------------------------------------------------------------------- | -------------- | @@ -428,7 +432,7 @@ Depending on the language there might be up to 6 forms. Following language speci | 4 | Special case for one and all numbers ending in `02`, `03`, or `04` | Slovenian | | 6 | Special cases for one, two, all numbers ending in `02`, `03`, … `10`, all numbers ending in `11` … `99`, and others | Arabic | -The [plural rules specification from the Unicode CLDR project](https://cldr.unicode.org/index/cldr-spec/plural-rules) contains a detailed linguistic analysis. +The [plural rules specification from the Unicode Common Locale Data Repository (CLDR)](https://cldr.unicode.org/index/cldr-spec/plural-rules) contains a detailed linguistic analysis. #### Use localization to handle pluralization From ba849a2ff8b8cf04e4a3998df6b78a40736970b0 Mon Sep 17 00:00:00 2001 From: Sandro Danioth Date: Tue, 24 Mar 2026 11:14:27 +0100 Subject: [PATCH 19/21] docs(localization): fix styling issues --- docs/fundamentals/localization.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/fundamentals/localization.md b/docs/fundamentals/localization.md index 557b3774c2..e15f271b6a 100644 --- a/docs/fundamentals/localization.md +++ b/docs/fundamentals/localization.md @@ -45,7 +45,7 @@ This page gives recommendations on how UX writers can support localization teams ### Consider translation -Translation-friendly texts should be created by UX writers thinking like a translator and asking the question: “Is the text understandable without the visual context?”. +Translation-friendly texts should be created by UX writers thinking like a translator and asking the question: “Is the text understandable without the visual context?”.
@@ -85,7 +85,7 @@ The handover documentation to development must include the UX writing specificat Common language serves multiple purposes: - Clarity of communication, common understanding between people and companies -- Applicability across multiple systems/tools/hardware, etc. +- Applicability across multiple systems/tools/hardware, etc. - Openness to third parties, breaking up of silos - Foundation for artificial intelligence From 25bb57242fab75f4c291d402bd615dd2c52ec833 Mon Sep 17 00:00:00 2001 From: Sandro Danioth Date: Tue, 24 Mar 2026 12:29:46 +0100 Subject: [PATCH 20/21] docs(localization): incorporate feedback from Jennie Co-authored-by: Sandro Danioth --- docs/fundamentals/localization.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/fundamentals/localization.md b/docs/fundamentals/localization.md index e15f271b6a..128eb36084 100644 --- a/docs/fundamentals/localization.md +++ b/docs/fundamentals/localization.md @@ -24,7 +24,7 @@ This example shows how values, dates, and times should be displayed after the pr ### Translation Translation is the central linguistic component of [localization](#localization-l10n), whereby the tone must be adapted to local requirements and the meaning must be conveyed accurately. -It is important to consider that languages differ in terms of word order, plural rules, and punctuation. +It is important for UX writers to consider that languages differ not only in terms of word order, plural rules, and punctuation, but an English word can have multiple meanings and be translated into other languages using completely different words. In addition, an English word can have multiple meanings and be translated into other languages using different words. ### LTR (Left-to-Right) @@ -196,7 +196,7 @@ Design user interfaces by following these steps to ensure that translations have Fixing UI issues caused by long translations late in the development cycle is expensive and time-consuming. -#### Awareness for length increase +#### Be aware of length increase Always design with translation in mind, assuming text will grow. @@ -207,7 +207,7 @@ Always design with translation in mind, assuming text will grow. - UI inconsistency Different languages require different amounts of space, which makes it difficult to maintain a consistent look and feel. -UX writers are ambassadors of internationalization and are asked to support UX designers in creating localization-friendly designs. +Keeping these differences in length for translations in mind supports the whole design team to create localization-friendly designs. #### Make space for translation @@ -373,7 +373,7 @@ Keep sentences understandable even with placeholders. -Use locale-aware formatting (see [Code tab](#code)), and avoid UX writing depending on a single format. +Use locale-aware formatting (see [Code tab](#code)), and avoid creating UI text that depends on one single format. This helps users to understand times, values, etc. and strengthens their confidence in using the system.
@@ -392,7 +392,7 @@ Use locale-aware formatting (see [Code tab](#code)), and avoid UX writing depend -### Pluralization +### Consider pluralization rules Each language has its own grammatical rules that specify how texts containing numbers must be presented. It is important to consider these different rules early in the UX writing and implementation process to ensure that the product can be localized correctly. From 988e3dcc9881657116aadbeb953015d19d857203 Mon Sep 17 00:00:00 2001 From: Sandro Danioth Date: Fri, 17 Apr 2026 13:33:36 +0200 Subject: [PATCH 21/21] docs(localization): incorporate Jennies feedback --- docs/fundamentals/localization.md | 27 +++++++++++++-------------- 1 file changed, 13 insertions(+), 14 deletions(-) diff --git a/docs/fundamentals/localization.md b/docs/fundamentals/localization.md index 128eb36084..03a2e57f38 100644 --- a/docs/fundamentals/localization.md +++ b/docs/fundamentals/localization.md @@ -46,6 +46,8 @@ This page gives recommendations on how UX writers can support localization teams ### Consider translation Translation-friendly texts should be created by UX writers thinking like a translator and asking the question: “Is the text understandable without the visual context?”. +In the example below, UX writers should ask themselves whether a tool instance is being deleted or whether something is being named. +It is also unclear whether “complete” is an adjective or a verb.
@@ -55,7 +57,7 @@ Translation-friendly texts should be created by UX writers thinking like a trans
-- `Delete complete tool instance ID naming`Deleting a tool instance?
Naming something?
Is "complete" an adjective or a verb? +- `Delete complete tool instance ID naming`
@@ -63,11 +65,9 @@ Translation-friendly texts should be created by UX writers thinking like a trans User interface texts are stand-alone, short, and to the point, but they provide little to no context on their own. Thus, translators and AI can only produce a reliable translation if the terms are - [Predominant](#terms-in-various-uses) -- [Precise](#domain-terminology) +- [Precise](#use-domain-terminology) - [Unambiguous](#avoid-misunderstandings) -UX writing combines terminology, style and form to ensure a consistent UI for specific use cases of a target audience. - ### Handover UX writing specifications @@ -89,7 +89,7 @@ Common language serves multiple purposes: - Openness to third parties, breaking up of silos - Foundation for artificial intelligence -#### Terms in various uses +#### Consider that terms are used in different ways Many terms have various meanings related to a specific context or domain. Use the terminology database of domain to maintain a common language. @@ -228,7 +228,7 @@ Consider German, Finnish, Greek, and some Slavic languages, which are known for #### Limit space if required Identify UI elements which truly offer limited space, even if a flexible design is the preferred choice. -The following UI elements may require text length restrictions: +The following UI elements may require text length restrictions, measured in either character count or pixel width: - Buttons - Tab labels @@ -236,8 +236,6 @@ The following UI elements may require text length restrictions: - Table headers - Input field labels -Texts can be limited by the translation management tool in terms of character count or pixel width. - ### Reuse texts Before writing a new text, check whether one with the exact same meaning already exists. @@ -258,15 +256,18 @@ Before writing a new text, check whether one with the exact same meaning already Reusing the same instance of text has the following advantages: -- …reduces the volume sent to translators and lowers cost. -- …increases the efficiency of product development and maintenance. -- …keeps translation unique in every supported language. -- …helps identifying duplicated functionality. +- reduces the volume sent to translators and lowers cost. +- increases the efficiency of product development and maintenance. +- keeps translation unique in every supported language. +- helps identifying duplicated functionality. However, be careful when changing approved, reused texts to ensure that their meaning is preserved. +### Consider different contexts + An English text may require different translations in different contexts. In such cases, a separate text must be created. +If in doubt, create a separate text for each use, even if the English text appears to be identical. @@ -289,8 +290,6 @@ In such cases, a separate text must be created. -If in doubt, create a separate text for each use, even if the English text appears to be identical. - ### Use translation libraries Packages based on the [Unicode CLDR](https://cldr.unicode.org/) like `@angular/common` and built-in runtime objects like `Intl` provide complete and high quality translations for: