index-en-US.md 37 KB
category: Getting Started title: Content Guidelines icon: doc-contentguidelines localeCode: en-US order: 11
brief: We are all keen to use Semi to create products that users like, and copywriting is the most direct communication method between products and users, and outputting correct and consistent copywriting is an indispensable part of product design.
Voice and Tone
Who will use our Guidelines and Principles?
Any role that engages in user-facing communication should follow the principles of voice and tone, such as: Product Manager, UX Writer, Developer, Designer, Marketer, … pretty much everyone.
Difference between Voice and Tone
Voice conveys the brand's unique point of view, perspective and identified values, that is, the personality of the product. The audience may be different, but our tone and personality remain the same. Tone is how a brand chooses to communicate with its users, including words, communication styles, and emotional attitudes. Our tone of voice will vary in different given scenarios.
Voice
As a modern, lightweight design system, we hope that every product created with Semi can also impress users with efficient expression. Based on this, we have established the following three principles as the brand voice: direct and clear, honest, helpful.
Direct and Clear
In order to help users complete their tasks efficiently, we usually communicate information directly, clearly and concisely.
Honest
Speak like a human, be empathetic, stand with users and help users solve problems.
Direct and Clear
We anticipate the real needs of users and provide assistance and information at the right time.
Tone
Our tone of voice adapts to different situations, just as you might change your tone when talking to a close friend or celebrating an important moment. We also adjust the tone when guiding users through a new feature, or telling them something doesn't work, or when they've completed a task. The following framework helps us determine the appropriate tone for each situation:
Neutral
Most of the time users want to complete their daily work quickly on the platform, and the copy we provide at this time is informative and useful.
Example: Add an image to a blank section to start building your website.
Celebratory
In some cases, we want to acknowledge that someone has completed a complex activity or difficult task. While we don't need to celebrate achievements, we should recognize the time and effort they put in. Depending on the level of effort, these might be simple confirmations or more aggressive acknowledgments that they accomplished something difficult.
Example:
- A slight celebration, the delivery action is complete: the file has been uploaded.
- A heavier celebration, suitable for completing complex tasks and giving users a sense of accomplishment: congratulations! You are a member of AnyWeb
Sympathetic
When users see an error message, they may get frustrated, their goal is to solve the current problem, and we hope to be able to show the problem directly and tell the solution (not recommended to use the sorry tone).
Example: The URL is not available. Contact the site administrator for help.
Helpful
Some people will want to be guided through the process step by step, while others may just want to try it out and learn on their own. Find ways to give them two options.
Example: Ready to create your first website? Get started with a 3-step trick.
Authoritative
Used in policy violations; such as when users engage in unacceptable behavior on the platform.
Example: Your site "Daily Coffee News" has been removed for policy violations.
Writing principles
Concise and Clear
Only need to provide the necessary information to the user, omit redundant unnecessary nonsense.
| ✅ Recommended usage | ❌ Deprecated usage |
|---|---|
| Don't know how to use it? [contact us]() | How to configure using SOP Questions? do not worry! You can contact us by clicking the icon below and our agent will help you solve the problem. |
Talk like a human
Present your message in the simplest and most understandable language possible, and try to avoid overly complex or incomprehensible language.
- Avoid coding languages
- Talk like a real person and avoid jargon
| ✅ Recommended usage | ❌ Deprecated usage |
|---|---|
| There was an error on the page, please try again later | 404 ERROR |
| Video loading... | Feed Stream Skeleton Loading... |
Straight to the point
Display the most important information first and minimize the input of non-high-quality information.
| ✅ Recommended usage | ❌ Deprecated usage |
|---|---|
| 3 steps to create a ticket | Create your ticket in 3 steps |
| file uploaded | you have successfully uploaded the file |
Be consistent
Consistency can make your product easier to understand. If a function/action is expressed in multiple ways, it will cause ambiguity to users. Every time you use a term or phrase appropriately and consistently, its meaning is strengthened.
- using terminology
| Term type | Example |
|---|---|
| brand name |
|
| industry term | For example, the translation industry MT = Machine Translation |
| platform terminology | For example, customer service platform en=Ticket，zh=工单 |
- Use consistent nouns and verbs Using different nouns, then the user will not be sure if the new word refers to the same thing. With different verbs, users may be unsure if a click will lead to the same result. Teams can sort out nouns or verbs that mean the same thing and choose one
| Chinese | English | ❌ Deprecated usage |
|---|---|---|
| 你 | You | 您 |
| 抱歉 | Sorry | 对不起 |
| 账号 | Account | 帐号 |
| 登录 | Log in | 登陆、Login（used only as a noun） |
| 退出登录 | Log out | |
| 新建 | Create | 创建 |
| 添加 | Add | 新增 |
| 删除 | Delete | 清除 |
| 移除 | Remove | |
| 启用 | Enable | 开启、开始使用 |
| 停用 | Disable | 暂停、停止使用 |
| 已启用 | Enabled | |
| 已停用 | Disabled | |
| 其他 | Other | 其它 |
| 时区 | Time zone | Timezone |
| English | English | （refers to the system language）EN |
| 中文 | 中文 | （refers to the system language）CN、Chinese |
| 注册 | Create account | Register、Sign up |
| 链接 | URL | Link |
Equal with users
- Try to avoid using the tone of pleading and apology to communicate with users, and only use 'sorry' or type of sorry language in very serious cases, such as the user's information is permanently and irreversibly deleted by the system. Under normal circumstances, simply explain why you are sorry and possible solutions
| ✅ Recommended usage | ❌ Deprecated usage |
|---|---|
| Click "Edit" to modify the content | Sorry, you cannot edit the form because you are in view mode. We apologize and ask you to click the "Edit" button to modify the form |
- At the same time, avoid using the tone of education, accusation and complaining to communicate with users
| ✅ Recommended usage | ❌ Deprecated usage |
| --- | --- |
| We did not recognize your password. For account security, you will not be able to log in for the next 30 minutes. | You have entered the wrong password several times and we consider this activity suspicious. We will not log you in for the next 30 minutes. |
Avoid exaggeration
Try to avoid absolute words like 'best', 'absolute', 'always' etc.
| ✅ Recommended usage | ❌ Deprecated usage |
| --- | --- |
| Starling will give you a good user experience |Compared to other translation platforms, Starling has the best user experience |
Gobalization
- Do not use words such as "overseas" to distinguish regions
| ✅ Recommended usage | ❌ Deprecated usage |
|---|---|
release area
|
release area
|
Inclusive
Inclusive language is language that does not contain words, phrases or intonations that reflect prejudices, stereotypes, or discriminatory views of a particular population or group.
Even if stereotype-based speech or behavior is not based on conscious bias, it can still be harmful and cause harm or discomfort to the person on the receiving end.
Age
Do not use words that describe age, such as "young", "old", etc.
Gender
Do not use gender-specific words to represent groups, such as "fireman" can be changed to "firefighter".
Others
- Do not use blacklists or whitelists
| ✅ Recommended usage | ❌ Deprecated usage |
|---|---|
| Add Key as disabled list | Add Key to blacklist |
- Consider color blind people
| ✅ Recommended usage | ❌ Deprecated usage |
| --- | --- |
| Click the "Accept" button | Click the green accept button |
- Don't use sensory verbs, focus on the end goal of the task, not the method to accomplish it
| ✅ Recommended usage | ❌ Deprecated usage |
| --- | --- |
| learn more | see more |
Grammar and Mechanics
1. Abbreviations
| Type | Unit | Full name | Abbreviation |
|---|---|---|---|
| area | metric | square meters | m² |
| Imperial | square feet | sq ft | |
| distance | metric | kilometers | km |
| Imperial | miles | mi | |
| length | metric | centimeters | cm |
| meters | m | ||
| Imperial | inches | in | |
| feet | ft | ||
| yards | yd | ||
| volume | metric | milliliters | ml |
| litres | L | ||
| Imperial | fluid ounces | fl oz | |
| gallons | gal | ||
| weight | metric | grams | ml |
| kilograms | kg | ||
| Imperial | ounces | oz | |
| pounds | lb | ||
| storage | - | kilobytes | KB |
| megabyte | MB | ||
| gigabytes | GB | ||
| terabytes | TB | ||
| month | - | January | Jan |
| February | Feb | ||
| March | Mar | ||
| April | Apr | ||
| June | Jun | ||
| July | Jul | ||
| August | Aug | ||
| September | Sep | ||
| October | Oct | ||
| November | Nov | ||
| December | Dec | ||
| week | - | Sunday | Sun |
| Monday | Mon | ||
| Tuesday | Tue | ||
| Wednesday | Wed | ||
| Thursday | Thu | ||
| Friday | Fri | ||
| Saturday | Sat | ||
| time | - | weeks | w |
| days | d | ||
| hours | h | ||
| minutes | m | ||
| seconds | s | ||
| amount | - | thousand | d |
| million | m | ||
| billion | B |
2. Acronyms
- If an abbreviation with a business attribute is used for the first time in a text paragraph, it can be directly explained through the text
- Example: Service Level Agreement (also known as SLA)
- If it is used in a component, it can be explained in the form of interaction of the component
- Example: Machine translation acronym for Starling
- Capitalize all letters
| ✅ Recommended usage | ❌ Deprecated usage |
| --- | --- |
| Create a new SLA| Create a new sla|
- Special scene: When displayed as an extended word, use lowercase letters for display
| ✅ Recommended usage | ❌ Deprecated usage |
| --- | --- |
| "image 12.png" failed to upload | "image 12.PNG" failed to upload |
3. Active vs. Passive Voice
- Active voice emphasizes who or what is doing the action
- Passive voice emphasizes the object being manipulated
In most cases, we recommend using the active voice because it provides greater clarity, reduces complexity, and sounds more like everyday conversation than passive voice. We can also use the passive voice when it doesn't matter who did the operation, or when the passive voice sounds more natural than the active voice (for example, verbs like publish or assign, and nouns like discount).
| ✅ Recommended usage | ❌ Deprecated usage |
| --- | --- |
| Eric uploaded a video. | The video was uploaded by Eric. |
| After you've added a product, click Save.| After the product has been added, Save must be clicked. |
| ✅ Recommended usage | ❌ Deprecated usage |
| --- | --- |
| Anyweb has published your website. | Your website was published. |
| We have removed our LIVE video due to a policy violation.| Your LIVE video was removed due to a policy violation. |
4. Articles
The use of articles ("the", "a", "an") in titles and copy depends on the situation. The situation is divided into whether the information to be expressed is conversational or call-to-action. Avoid using articles in buttons and labels.
Conversational messages
For more conversational parts, such as Home cards, marketing copy, and empty states, use the article. This makes the language sound more approachable and helps users understand complex concepts they encounter for the first time.
| ✅ Recommended usage | ❌ Deprecated usage |
|---|---|
| Start building your website by adding a text element to a blank section. | Start building your website by adding text element to blank section. |
Call-to-action
On buttons, action-oriented dialog titles, and menu titles, you can drop the article.
| ✅ Recommended usage | ❌ Deprecated usage |
|---|---|
| Add menu item | Add a menu item |
| Upload video? | Upload a video? |
5. Capitalization
Sentence case
1. In most cases, the content in the platform is in the form of Sentence Case, such as a paragraph of text, a sentence, a title, and UI elements (button names, labels, menus, etc.)
| ✅ Recommended usage | ❌ Deprecated usage |
|---|---|
| Create project | Create a Project |
2. Sentences starting with a number, the first letter does not need to be capitalized
| ✅ Recommended usage | ❌ Deprecated usage |
|---|---|
| 2 results found | 2 Results found |
3. A letter after a slash needs to be capitalized
| ✅ Recommended usage | ❌ Deprecated usage |
|---|---|
| Country/Region | Country/region |
| Turn on the On/Off toggle. | Turn on the On/off toggle. |
Title Case
Usually, when referring to proper nouns, the way Title Case is used is reasonable.
1. Proper nouns, such as terms, brand names, platform names, function names, trademarks, etc., must be capitalized
| ✅ Recommended usage | ❌ Deprecated usage |
|---|---|
| Do you want to return Yves Saint Laurent lipstick? | Do you want to return Yves saint laurent lipstick? |
- When the person's name follows the job title and title, the first letter of the word must be capitalized, such as UX Writer, Jackie, Headmaster Li, etc.
2. Other cases
- proper noun need to be capitalized anywhere in the interface
- a, an, prepositions such as on, to, in, up, down, of, for, etc., and, but, or, not, yet, etc., do not need to be capitalized at any time except at the first letter of the segment
- For multiple words connected by hyphens, the first letter of each content word is capitalized, and the first letter of function words is lowercase, such as Starling-in-Context
- For file names suffixed with
.xlsx, underscore is used to separate each word in English, and Title Case rules are used for capitalization, such as Salary_Data_Repair_Template.xlsx - If the English in parentheses is a complete sentence, the first letter is capitalized; if it is not a complete sentence, the first letter is lowercase
6. Contractions
Abbreviations are abbreviations for words, such as: what's, where's, we'll, we're, you'll, you're, they're, doesn't, didn't, isn't, aren't or can't. We use abbreviations to create a relaxed and human tone.
- Abbreviations are recommended as they make the content more conversational
- Don't use informal abbreviations like: ain't, y'all
- Don't use less common abbreviations like: would've, could've, it'll
- Be careful when abbreviating "is," "does," "has," "was," because their abbreviations are similar to possessives (such as "John's shirt"), making the information less readable. For example👇
| ✅ Recommended usage | ❌ Deprecated usage |
|---|---|
| maxattacks is currently livestreaming | maxattacks's currently livestreaming |
- For some sensitive or serious information, such as error information or account closure information, try to avoid using abbreviated forms, but put the clarity of the information and the respect for the situation first
| ✅ Recommended usage | ❌ Deprecated usage |
|---|---|
| Can't, don't, it's | cannot, do not, it is |
|
|
7. Emoji
Avoid emoji, opt for an icon instead; use it at the end of a segment if you must.
8. Date and Time
Unified specification
- Use 24-hour clock to represent time, such as 07:00, 21:00, do not use am, pm
Date
Example: Jan 1, 2018, 2018–01–01
- If there is enough space, write the date in full. Such as: March 12, 2020
- If space is limited, the month can be abbreviated. Such as: Mar 12, 2020
- Use dashes – (Option and -) to connect year, month and day, do not use / , such as: en: 03/01/2022; zh: 2022-03-01
- Month abbreviations use three letters, Jan, Feb, Mar, Apr
- Months cannot be abbreviated when not used to represent a date. Such as: Registered at Septemter
- Avoid using numeric abbreviations for dates, such as "first" "1st" "23rd"
- A module can only use one time format
- The calendar starts on Monday, which is the custom in most parts of the world
Timestamp
Follow the example below to use a consistent timestamp format.
| less than 1 minute | Just now | |
| 1–60 minutes | 13 minutes ago | |
| Today | 10:30 | |
| Yesterday | Yesterday at 10:30 | |
| last 7 days | Friday at 10:30 | |
| 7 days – 1 year | Aug 14 at 10:30 | 08–14 10:30 |
| more than 1 year | Aug 14, 2016 at 10:30 | 2016–08–14 10:30 |
Time Range
In principle, both the tilde "~" and the dash "-" can indicate a range. Since there is already "-" in the time to distinguish the table, use "~" uniformly.
Example: 2020-02-06 ~ 2020-02-08
Duration
| Time dimension | English format |
|---|---|
| second | 5sec / 5s |
| minute | 20min 5sec / 20m 5s |
| hour | 23hrs 8min 5sec / 23h 8m 5s |
| day | 3 days |
| week | 1 week |
| month | 3 months |
| year | 1 year |
- If the timing is displayed in the middle of a sentence (such as in a banner), use the form to display the specific time unit
- If the countdown unit exceeds 24 hours, display the day and hour, such as "2 days 1:50"
- If the duration is up to days, display the hours, such as "1 hour 50 minutes"
- If the maximum time is up to points, display the points, such as "50 points"
9. e.g., i.e, etc.
Avoid Latin abbreviations, as these abbreviations may not be understood by everyone.
| ✅ Recommended usage | ❌ Deprecated usage |
|---|---|
| for example, such as | e.g. |
| that is | i.e. |
| Add sounds, effects, stickers and more. | Add sounds, effects, stickers, etc. |
10. Lists
- Use lists to increase the readability of information. If the list is a complete statement, use proper punctuation. Try to ensure that the list content is less than or equal to six. If the list contains more than six items, try dividing it into multiple lists
- To make your list more local, start with an introductory statement and end with a colon ":". Try to avoid repeating phrases, and if some word is relevant to all the list contents, try putting it in the introductory statement
| ✅ Recommended usage | ❌ Deprecated usage |
|---|---|
Your viewers can find your videos from the following source:
|
Your viewers can find your videos from
|
- When writing list contents, use parallel statements. For example, if you're describing some behavior and begin with a verb, make sure the rest of the list follows the same pattern
| ✅ Recommended usage | ❌ Deprecated usage |
|---|---|
You can make these changes from your profile:
|
You can make these changes from your profile:
|
- Keep the first letter of the first word of the list in uppercase
- Do not use any punctuation at the end of the list content, treat each list content as a separate message
Bulleted
Unordered lists are used when the contents of the list are related, but not related to order or priority. The first letter of the sentence in the list is capitalized, no period is required.
| ✅ Recommended usage | ❌ Deprecated usage |
|---|---|
Use Pear Payments to:
|
Use Pear payments to
|
Numbered
Ordered lists are used when the content of the list is related to order and priority. The first letter of the sentence in the list is capitalized, no period is required.
| ✅ Recommended usage | ❌ Deprecated usage |
|---|---|
To add a new user macro:
|
To add a new user macro:
|
11. Dropdown menus
Menu information gives the user a set of horizontal operation information. The order of menu information is based on logic, such as the most frequently used operations. These operation information try to follow the style of "verb + noun", if the context information is enough, you can also use only "verb".
| ✅ Recommended usage | ❌ Deprecated usage |
|---|---|
|
|
12. Number
General rules
- Separate numbers with commas if they are four digits or more
- Example：$2,353.56, 5,345 MB
- There will be some special cases where numbers do not need to be separated by commas
- Example
- Address：3515 Montgomery St
- Page：page 1294
- Year：2022
- Resolution：1920 x 1080
- A space is required between the number and the unit
- Example：5,345 MB, 7 lb
Currency
- When used in formal occasions (such as transaction details, order details), the complete currency format is displayed. It is recommended to use this display format by default
| ✅ Recommended usage | ❌ Deprecated usage |
|---|---|
 |
 |
- If necessary, the ISO code of the currency can be displayed for differentiation
- Example：$12.00 CAD，$12.00 USD
Phone number
- Use parentheses to show area codes
- Example：(000) 000-0000
Number range
- Use a bar to separate the number range, and do not add spaces before and after the bar
| ✅ Recommended usage | ❌ Deprecated usage |
|---|---|
| 2:00 pm-3:00 pm | 2:00 pm - 3:00 pm |
| Jan 15-Jan 31 | Jan 15-31 |
| 10-100 lb | 10 - 100lb |
| Jan 1-15 | Jan 1 - 15 |
| 4-5 days | 4 - 5 days |
13. Punctuation
Ampersands
Do not use "&" except for proper nouns (such as Abercrombie & Fitch ), use "and" instead of "&".
| ✅ Recommended usage | ❌ Deprecated usage |
|---|---|
| Sun and moon | Sun & moon |
Apostrophes
- Use apostrophes to replace omitted letters and numbers:
- Omitted number：'40s
- Omitted letter：don't, isn't shouldn't
- Abbreviation of verb：it's, you're, they're
- Use apostrophes to form ownership：
- Add 's to singular nouns, even if the last letter of the noun ends in s: bus's, computer's
- Plural nouns whose last letter does not end in s plus 's: women's, men's
- Plural nouns ending in an s with the last letter just add the apostrophe, don't need s: boxes', bottles'
Colons
- Try to avoid using colons in sentences. If you want to use them, the first letter of the first word after the colon does not need to be capitalized, unless it is a technical term
- Use colons to import lists
| ✅ Recommended usage | ❌ Deprecated usage |
|---|---|
Pay attention to the following rules:
|
Pay attention to the following rules.
|
Commas
- If there are multiple commas in a sentence, you can split the sentence into multiple shorter sentences
- Use the oxford comma, also known as the serial comma, which is the last comma before "and" or "or" in the list
| ✅ Recommended usage | ❌ Deprecated usage |
|---|---|
| The study shows that the patients enjoyed reading, sleeping, and cooking. | The study shows that the patients enjoyed reading, sleeping and cooking. |
- Do not use commas to separate bulleted or numbered list items
| ✅ Recommended usage | ❌ Deprecated usage |
|---|---|
Pay attention to the following rules:
|
Pay attention to the following rules:
|
Dashes and hyphens
- Use dashes to show ranges of numbers without spaces before and after the numbers
| ✅ Recommended usage | ❌ Deprecated usage |
|---|---|
| 23–52 | 23 – 52 |
| Jan.14 – Feb.23 | Jan.14–Feb.23 |
- When two adjectives need to be combined to describe the following noun, use a hyphen
| ✅ Recommended usage | ❌ Deprecated usage |
|---|---|
| Start your 14-day trial. | Start your 14 day trial. |
| We’re looking for a dog-friendly hotel. | We’re looking for a dog friendly hotel. |
- For some common combined words, hyphens do not need to be used. For details on whether hyphens are required, please refer to the dictionary
- Notebook
- Bookstore
- Fireman
- Superman
- Concatenate prefixes with hyphens
| ✅ Recommended usage | ❌ Deprecated usage |
|---|---|
| Do you want a self-serve or a full-serve gas station? | Do you want a self serve or a full serve gas station? |
Ellipses
- Use ellipses when an action is in progress
- Example：uploading...
- When some components cannot display all the text under the limited width, use ellipsis to truncate
Exclamation points
Try to avoid exclamation marks unless it's really exciting. If you want to use it, use an exclamation mark.
Periods
- If there are multiple sentences in a paragraph, use a period at the end of each sentence and add a space after the period
- Do not use periods in the following scenarios：
- Button
- Toast with one sentence
- Placeholder
- Title
- Notice
- Navigation bar menu
- Tooltip
- Radio
- Checkbox
Question marks
- The question (and question mark) can be shown when the answer to the question is not known
- Example：Forget password?
- If it is a non-question sentence, do not use a question mark
- Example：Reset password
Quotation marks
- Use quotation marks to refer to defined nouns, and quotation marks to indicate user-entered information, such as titles and file names
| ✅ Recommended usage | ❌ Deprecated usage |
|---|---|
| Delete "[email protected]"? | Delete [email protected]? |
| "image 3234.png" failed to upload | image 3234 failed to upload |
| To remove this item, click "Delete". | To remove this item, click "Delete." |
Semicolons
Don't use semicolons, Try to split a sentence into multiple shorter sentences。
Slashes
- When there is enough space, use "or" instead of slashes to display, if there is not enough space, you can use slashes
- The letter after the slash does not need to be capitalized
| ✅ Recommended usage | ❌ Deprecated usage |
|---|---|
| Single/plural | Single/Plural |
14. Pronouns
- In most cases, use the second person ("you") to communicate with users
- Example：When's your birthday?
- Avoid first-person pronouns ("I" or "my"), as using such pronouns can confuse users about who you are referring to, with the exception of some legal terms
- Avoid unnecessary pronouns (unless they affect the tone of the message)
| ✅ Recommended usage | ❌ Deprecated usage |
|---|---|
| Edit profile | Edit my profile |
15. Prefix
Prefixes are used to add in front of a word to become a new word; by adding prefixes, you can use to enhance or change the meaning of a word;
Avoid using prefixed words in headings, paragraphs, tags, etc., need to spell out all letters of the word to minimize comprehension difficulties during localization.
| ✅ Recommended usage | ❌ Deprecated usage |
|---|---|
| instantly generated | insta-generated / instantiated |
If it is used frequently within the product due to space constraints, or as a feature name, prefix usage such as "auto-generated" instead of "automatically generated" can be used
16. UI elements
When the copy refers to other UI elements in the product, the copy needs to be bolded.
Expamle：Remove from Saved
It is not recommended to use ("") when expressing UI elements, unless there is no way to use the bold effect.