semi-design/content/start/content-guidelines/index-en-US.md

---

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	ByteDance Semi
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 China Non-China Region	release area China Overseas

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
You can’t have products with negative weights Your products don’t have weights You’re all set up This product doesn’t require shipping The customer name shouldn’t contain numbers It’s a good time to plan your Black Friday sale An error occurred and your changes couldn’t be saved I’m Kit, your digital marketing assistant This transfer hasn’t been received You haven’t connected your account You’ve exceeded 10 password attempts	That’ll make sure you are all set up It would’ve been possible if you’d installed the latest updates The set up was not complete, but this’ll do There’re 10 products in this collection Your product mustn’t be more than 20kgs This product needn’t be shipped There are 3 visitors who’ve viewed this product It’d be a good idea to place an ad this weekend

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: For You Following Discover	Your viewers can find your videos from For You feed Following feed Discover

• 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: Edit your bio Add a nickname Change your username	You can make these changes from your profile: Edit your bio Nickname: Edit or add You can change your username

• 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: Avoid the hassle of setting up a third-party payment gateway Track your payout schedule from the Pear admin Minimize lost sales from chargebacks	Use Pear payments to avoid the hassle of setting up a gateway, track pending payout schedule, minimize lost sales from chargebacks. And eliminate PCI fees

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: Go to "Settings" Choose "Create a user macro" Enter the macro details	To add a new user macro: Go to "Settings" Choose "Create a user macro" Enter the macro details

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
Rename Edit HTML Duplicate	File name changes editing options HTML Duplicate this order so that you can make edits, updates, or changes

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: Add a space between character and number Don't use semicolons	Pay attention to the following rules. Add a space between character and number Don't use semicolons

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: Add a space between character and number Don't use semicolons	Pay attention to the following rules: Add a space between character and number, Don't use semicolons

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.

References

• Accessible-and-inclusive-language
• Atlassian design: Inclusive language
• Clarity Design Copywriting
• Microsoft's brand voice: Above all, simple and human
• Mailchimp Content Style Guide: Voice and Tone
• Hyphen Usage-Rules and Examples
• How to define your brand's Tone of Voice: Infigraphics & Examples?