Overview

#

In general, we follow Material Design's writing guidelines. Our slightly adapted version is below.

Language & tone

#

Most of these tips are the same as Material's guidelines:

• Address the user as 'you', and avoid using 'we'
• Use the gender-neutral singular 'they'
• Be concise
• Write in the present tense
• Write simply and directly
• Write for all levels of readers - do not use complex terminology
• Use consistent words in all parts of the app
• “1, 2, 3” not “one, two, three”
• Reveal detail as needed
• Be positive
• Communicate only essential details

In Kolibri products, avoid creating new Proper Nouns in casual messages. For example, "You are a coach", not "You are a Coach". See also the Glossary page which outlines terms that have a specific meaning in the Kolibri product ecosystem.

Punctuation

#

• Use "Sentence case" capitalization for titles, not "Title Case" capitalization
• Skip periods and unnecessary punctuation
• Use contractions when they make a sentence easier to understand
• Avoid exclamation marks
• Always wrap user-generated text in 'single quotes'

Internationalization

#

All user-facing text and iconography needs to be internationalized. For text strings, numbers, dates, and times, this means "wrapping" the messages such that they can be mapped to messages in other languages using the ICU message syntax. See our developer docs for more information.

Phrases that might not be globally understood should be avoided because they will be cause issues with translation.

Note that currently our i18n framework does not support formatting such as bold or italics within a translated string.

The built-in components in this guide support right-to-left languages out of the box. If you design or build custom components, these need to be fully tested using an RTL language. We use a webpack plugin to automatically flip most of the CSS, and the global isRtl attribute on all Vue components can be used to customize behavior if necessary.

To properly support right-to-left languages and bi-directional text in custom components, follow the following guidelines:

• No displayed user data or content should have right or left set for the text-align property (center is OK)
• All displayed user data and content should have dir="auto"
• dir="auto" should not generally be set on 'wrapper' nodes - it should be as close to the text as possible
• Translated "app text" does not generally need to have dir="auto"