diff --git a/blog/tags.yml b/blog/tags.yml index 9dd7707f0..deca5a750 100644 --- a/blog/tags.yml +++ b/blog/tags.yml @@ -2,3 +2,7 @@ release: description: 'Blog posts about new Industrial Experience design system releases' merging: description: 'Merging activities from other design systems at Siemens' +ux: + description: 'User experience patterns, recommendations, and writing guidance' +development: + description: 'Developer-focused implementation tips, APIs, and code practices' diff --git a/docs/guidelines/language/support-and-resources/AI-and-UX-writing.md b/docs/guidelines/language/support-and-resources/AI-and-UX-writing.md index fa78c0f42..fc22f5ef5 100644 --- a/docs/guidelines/language/support-and-resources/AI-and-UX-writing.md +++ b/docs/guidelines/language/support-and-resources/AI-and-UX-writing.md @@ -1,5 +1,5 @@ --- -sidebar_position: 2 +sidebar_position: 4 sidebar_label: AI and UX writing title: AI and UX writing doc-type: "banner" diff --git a/docs/guidelines/language/support-and-resources/UX-writing-principles.md b/docs/guidelines/language/support-and-resources/UX-writing-principles.md index 2074b54c5..4d6bdec18 100644 --- a/docs/guidelines/language/support-and-resources/UX-writing-principles.md +++ b/docs/guidelines/language/support-and-resources/UX-writing-principles.md @@ -1,5 +1,5 @@ --- -sidebar_position: 1 +sidebar_position: 2 sidebar_label: UX writing principles title: UX writing principles doc-type: 'banner' diff --git a/docs/guidelines/language/support-and-resources/UX-writing-resources.md b/docs/guidelines/language/support-and-resources/UX-writing-resources.md index 52fbe3cba..5f3115c73 100644 --- a/docs/guidelines/language/support-and-resources/UX-writing-resources.md +++ b/docs/guidelines/language/support-and-resources/UX-writing-resources.md @@ -1,5 +1,5 @@ --- -sidebar_position: 4 +sidebar_position: 5 sidebar_label: UX writing resources title: UX writing resources doc-type: "banner" diff --git a/docs/guidelines/language/support-and-resources/ux-writer-role.md b/docs/guidelines/language/support-and-resources/ux-writer-role.md index a33aeff8b..c7ffd9dfc 100644 --- a/docs/guidelines/language/support-and-resources/ux-writer-role.md +++ b/docs/guidelines/language/support-and-resources/ux-writer-role.md @@ -1,5 +1,5 @@ --- -sidebar_position: 3 +sidebar_position: 1 sidebar_label: UX writer role title: UX writer role doc-type: 'banner' @@ -115,4 +115,4 @@ Continuous collaboration improves quality and speed, prevents terminology gaps, ## Related - [UX writing principles](./UX-writing-principles.md) -- UX writing support and resources (coming soon) \ No newline at end of file +- UX writing support and resources (coming soon) diff --git a/docs/guidelines/language/support-and-resources/uxw-localization/_category_.json b/docs/guidelines/language/support-and-resources/uxw-localization/_category_.json new file mode 100644 index 000000000..bc6d0291b --- /dev/null +++ b/docs/guidelines/language/support-and-resources/uxw-localization/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Localization", + "position": 3 +} diff --git a/docs/guidelines/language/support-and-resources/uxw-localization/index.mdx b/docs/guidelines/language/support-and-resources/uxw-localization/index.mdx new file mode 100644 index 000000000..06ef45b97 --- /dev/null +++ b/docs/guidelines/language/support-and-resources/uxw-localization/index.mdx @@ -0,0 +1,6 @@ +--- +doc-type: "tabs" +description: 'Localization (l10n) is the adaptation of a product or content for a specific language, locale, region or market.' +title: 'Localization' +deprecated: +--- diff --git a/docs/guidelines/language/support-and-resources/uxw-localization/overview.md b/docs/guidelines/language/support-and-resources/uxw-localization/overview.md new file mode 100644 index 000000000..39458a101 --- /dev/null +++ b/docs/guidelines/language/support-and-resources/uxw-localization/overview.md @@ -0,0 +1,97 @@ +--- +doc-type: 'tab-item' +sidebar_label: 'Localization' +description: 'Overview' +--- + +# + +## Overview + +Localization adapts a product to a specific language, region, and culture. It includes +translation, formats, visual conventions, legal requirements, and user expectations. + +## Language and tone + +Language and tone must be clear, accurate, and appropriate for the target audience. Good +localization preserves meaning, not just words, and must also account for plural rules and +punctuation. + +### Best practice + +- Support translatable strings and integration with translation frameworks. +- Support fallback text for missing translations. +- Use the [UX Writing Guidelines](../../writing-style-guide-getting-started.md) for tone or wording. + +## Imagery and colors + +Images, symbols, and colors can have different meanings across markets. Review them for cultural +fit and local expectations. + +### Best practice + +- Validate visuals and semantics per market. + +## Currency, date, time, measurement, and measurement system formats + +Users expect values to follow local conventions. This includes currencies, dates, times, numbers, +units, and measurement systems such as °C/°F, km/mi, or kg/lb. + +### Best practice + +- Use locale-aware formatting for dates, times, numbers, percentages, and currencies. +- Allow users locale selection and persistence, e.g. via the `SiLocaleService`. +- Use translated unit labels in components where units are shown. + +## User experience and design + +Localized interfaces must work with different text lengths and different reading directions. Use +design options such as flexible growing areas, line wrapping, or fixed layouts with scrollbars, +and plan enough space for longer translations. + +## LTR and RTL {#ltr-rtl} + +LTR (Left-to-Right) refers to languages and scripts that are written and read from left to right. + +RTL (Right-to-Left) refers to languages and writing systems that are written and read from right to left. +RTL can require mirrored navigation, icon direction, alignment, and interaction patterns. + +### Best practice + +- Support RTL-aware behavior in components and overlays. +- Provide dynamic directionality support for Angular CDK integrations. +- Layout and design with variable text length in mind. + +## Payment methods + +Payment expectations differ by country, including preferred methods, flows, and trust signals. + +## Legal and safety + +Legal notices, safety texts, consent flows, and compliance content may vary by market and +jurisdiction. + +### Best practice + +- Request local lawyers to provide tailored legal artifacts for relevant markets and regions. +- Manage market-specific legal and safety requirements, compliance logic, and legal services in your application. + +:::info +The About and Legal components require specific content to comply with Siemens AG regulations. The official content and guidelines are exclusively available for Siemens employees and can be accessed [here](https://code.siemens.com/siemens-ix/ix-brand-theme/-/blob/main/apps/documentation/src/pages/about-legal-information.md?ref_type=heads). +::: + +## Customer support + +Support channels, contact details, hours, and escalation paths often differ by country or +language. + +## Localization (l10n) vs. Internationalization (i18n) + +Internationalization (i18n) is the technical preparation that makes localization possible without +code changes. Typical activities include separating translatable text from code, enabling +locale-aware formatting, supporting plural rules, and preparing layouts for text expansion and +RTL. + +Localization (l10n) is the adaptation of content and behavior for a specific market, language, or +region. Typical activities include translation, terminology review, adapting formats and units, +checking imagery and legal content, and validating the user experience for the target audience. diff --git a/docs/guidelines/language/support-and-resources/uxw-localization/writing.mdx b/docs/guidelines/language/support-and-resources/uxw-localization/writing.mdx new file mode 100644 index 000000000..7fbc20279 --- /dev/null +++ b/docs/guidelines/language/support-and-resources/uxw-localization/writing.mdx @@ -0,0 +1,427 @@ +--- +doc-type: 'tab-item' +sidebar_label: 'Writing' +description: 'Writing guidance for localization.' +--- + +# UX writing and localization + +UX writers are the text experts in the product development team and therefore should understand localization. This page gives recommendations on how UX writers can support localization teams and translators to minimize internationalization challenges. + +## Consider translation + +Create translation-friendly texts while 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. + +
+
+ +
+
+ +
+
+ +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 +- Precise +- Unambiguous + +## Use domain terminology + +Use terms from standardization bodies (e.g. [ISO](https://iso.org), [EN](https://cen.eu), [UL](https://ul.com), [IEC](https://iec.ch)) or experts from universities and global specialized companies, but avoid terms from quasi-industrial standards. + +
+
+ +
+
+ +
+
+ +Note: The [Commission Regulation (EU) 2023/826](https://eur-lex.europa.eu/eli/reg/2023/826/oj?uri=CELEX:32023R0826) specifies the maximum power consumed by a device (e.g., 0.5 W) in order to use the term “standby". + +Common language serves multiple purposes: + +- Clarity of communication, common understanding between people and companies +- Applicability across multiple systems, tools, hardware, etc. +- Openness to third parties, breaking up of silos +- Foundation for artificial intelligence + +## Consider that terms are used in different ways + +Many terms have various meanings related to a specific context or domain. +Use the terminology domain database to maintain a common language. +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. + +### Example: The term "title" and its meanings + +- 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 +- All the elements constituting legal ownership +- A descriptive or general heading (as of a chapter in a book) + +One meaning always dominates regardless of context. That is the meaning that can be used without creating confusion. However, if this dominant meaning does not fit the context, an alternative term (unambiguous synonym) must be used to eliminate misunderstandings. + +
+
+ +
+
+ +
+
+ +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). + +## Avoid misunderstandings + +Avoid possible causes of misunderstandings by: + +- Grouping the texts by use cases. +- Only using the predominant meaning of the term. +- Annotating texts with a description (if supported by translation framework and file format). + +## Avoid directional terms on UI + +Directional terms might be incorrect if the user interface is mirrored for [RTL languages](./overview.md#ltr-rtl). +Use direction agnostic texts instead. + +
+
+ +
+
+ +
+
+ + +## Manage space for translations + +Follow these steps to ensure that translations have enough 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 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 in languages known for their long translations (German, Finnish, Greek and some Slavic languages). +1. 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. + +## Be aware of length increase + +Always design with translation in mind, assuming text will grow: + +1. **Layout breakage:** Fixed-width elements may not accommodate longer text, which can result in overflows, line breaks in awkward places, or text disappearing completely. +2. **Truncation:** If text is truncated, important instructions or information may be invisible, which can lead to frustration and misuse. +3. **UI inconsistency:** Different languages require different amounts of space, which makes it difficult to maintain a consistent look and feel. + +Keeping these differences in length for translations in mind supports the whole design team to create localization-friendly designs. + +Although the exact length of a translation cannot be predicted, there are some generally accepted rules of thumb: + +- Short texts (1-10 characters) typically increase by 200-300% (e.g. EN: "On" → DE: "Eingeschaltet"). +- Medium texts (11-20 characters) typically increase by 100-200% (e.g. EN: "Withdraw request" → DE: "Anfrage zurückziehen"). +- Longer texts (21-50 characters) typically increase by 50-100%. + Very long texts (50+ characters) typically increase by 30-50% but are sometimes shorter than the original. + +## 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, measured in either character count or pixel width: + +- Buttons +- Tab labels +- Navigation menu items +- Table headers +- Input field labels + +## 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. + +### Pluralization examples + +Pluralization of the English term "apple": +- 0: I own no 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 + +## 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. + +
+
+ +
+
+ +
+
+ +## Consider different linguistic rules + +Depending on the language there might be up to 6 forms. The following language specific variability exists: + +| 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 | + +The [plural rules specification](https://cldr.unicode.org/index/cldr-spec/plural-rules) from the Unicode Common Locale Data Repository (CLDR) contains a detailed linguistic analysis. + +## Provide user-friendly language selection + +Provide each language name in the target language for the language switcher. + +
+
+ +
+
+ +
+
+ +## Avoid text concatenations + +Building sentences from fragments prevents correct grammar in many languages. +Keep sentences as one unit with placeholders. + +
+
+ +
+
+ +
+
+ +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 + +Keep sentences understandable even with placeholders. + +
+
+ +
+
+ +
+
+ +## Avoid hard-coding formats + +Use locale-aware formatting, 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. + +
+
+ +
+
+ +
+
+ +## Provide UX writing specifications + +Providing project-specific UX writing specifications helps developers group texts by use cases and determine when a text can be reused or whether a specific context needs to be taken into account. +Non-concatenated texts with readable placeholder names, combined with translation libraries, enable efficient, high-quality localization. + +## Group texts + +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. My account → Theme selection) along with meaningful (key) names. + +
+
+ +
+
+ +
+
+ +## Reuse texts + +Before writing a new text, check whether one with the exact same meaning already exists. + +
+
+ +
+
+ +
+
+ +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. + +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. + +
+
+ +
+
+ +
+
+ + +## 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: + +- Language and script names +- Countries +- Regions +- Currencies +- Months and days +- Time zones + +:::info +For Siemens employees and partners, the Element design system provides pretranslated texts for components and can be accessed [here](https://simpl.code.siemens.io/simpl/development/language-packs). +::: diff --git a/sidebars.ts b/sidebars.ts index 3f2669f88..4eaf98136 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -1201,8 +1201,79 @@ const sidebars: SidebarsConfig = { label: 'UX Writing', items: [ { - type: 'autogenerated', - dirName: 'guidelines/language', + type: 'category', + label: 'Basics', + items: [ + { + type: 'autogenerated', + dirName: 'guidelines/language/basics', + }, + ], + collapsed: true, + }, + 'guidelines/language/grammar-and-vocabulary', + { + type: 'category', + label: 'Formatting', + items: [ + { + type: 'autogenerated', + dirName: 'guidelines/language/formatting', + }, + ], + collapsed: true, + }, + 'guidelines/language/dialogs-and-buttons', + 'guidelines/language/frequent-app-functions', + { + type: 'category', + label: 'Messaging', + items: [ + { + type: 'autogenerated', + dirName: 'guidelines/language/messaging', + }, + ], + collapsed: true, + }, + { + type: 'category', + label: 'Menu functions and UI labels', + items: [ + { + type: 'autogenerated', + dirName: 'guidelines/language/menu-functions-and-ui-labels', + }, + ], + collapsed: true, + }, + 'guidelines/language/proper-nouns', + 'guidelines/language/punctuation', + 'guidelines/language/writing-style-guide-getting-started', + { + type: 'category', + label: 'Support and resources', + items: [ + 'guidelines/language/support-and-resources/ux-writer-role', + 'guidelines/language/support-and-resources/UX-writing-principles', + 'guidelines/language/support-and-resources/AI-and-UX-writing', + createTabItem({ + id: 'guidelines/language/support-and-resources/uxw-localization/index', + label: 'Localization', + items: [ + { + id: 'guidelines/language/support-and-resources/uxw-localization/overview', + label: 'Overview', + }, + { + id: 'guidelines/language/support-and-resources/uxw-localization/writing', + label: 'Writing', + }, + ], + }), + 'guidelines/language/support-and-resources/UX-writing-resources', + ], + collapsed: true, }, ], collapsed: true, diff --git a/src/theme/DocItem/Layout/index.tsx b/src/theme/DocItem/Layout/index.tsx index 328d4478a..339c1a5ac 100644 --- a/src/theme/DocItem/Layout/index.tsx +++ b/src/theme/DocItem/Layout/index.tsx @@ -115,10 +115,15 @@ export function DocItemTabsLayout(): JSX.Element { const history = useHistory(); const { metadata } = useDoc(); - const sidebar = useCurrentSidebarCategory() as { items: { href: string }[] }; + let sidebar: { items?: { href: string }[] } | undefined; + try { + sidebar = useCurrentSidebarCategory() as { items?: { href: string }[] }; + } catch { + sidebar = undefined; + } useEffect(() => { - if (sidebar.items.length > 0) { + if (sidebar?.items && sidebar.items.length > 0) { history.push(sidebar.items[0].href); } }, [sidebar]); @@ -136,11 +141,22 @@ export function DocItemTabItemLayout({ children }: Props): JSX.Element { const doc = useDoc(); const { metadata } = doc; - const sidebar = useCurrentSidebarCategory(); + let sidebar: { items?: PropSidebarItemLink[] } | undefined; + try { + sidebar = useCurrentSidebarCategory() as { items?: PropSidebarItemLink[] }; + } catch { + sidebar = undefined; + } - const parentId = metadata.id.split('/').slice(0, -1).join('/') + '/index'; + // Resolve the parent tabs document relative to the current tab-item depth. + const parentId = `${metadata.id.split('/').slice(0, -1).join('/')}/index`; const parentDoc = useDocById(parentId); + const tabs = + sidebar?.items && sidebar.items.length > 0 + ? (sidebar.items as PropSidebarItemLink[]) + : []; + return ( <>