Start · Content Guidelines
Content Guidelines
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.
semi voice
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 usHow 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 later404 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 ticketCreate your ticket in 3 steps
file uploadedyou 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 typeExample
brand name
  • ByteDance
  • Semi
industry termFor example, the translation industry
MT = Machine Translation
platform terminologyFor 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
ChineseEnglish❌ 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 zoneTimezone
EnglishEnglish(refers to the system language)EN
中文中文(refers to the system language)CN、Chinese
注册Create accountRegister、Sign up
链接URLLink
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 contentSorry, 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 experienceCompared 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 listAdd Key to blacklist
  • Consider color blind people
✅ Recommended usage❌ Deprecated usage
Click the "Accept" buttonClick 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 moresee more

Grammar and Mechanics

1. Abbreviations

TypeUnitFull nameAbbreviation
areametricsquare meters
Imperialsquare feetsq ft
distancemetrickilometerskm
Imperialmilesmi
lengthmetriccentimeterscm
metersm
Imperialinchesin
feetft
yardsyd
volumemetricmillilitersml
litresL
Imperialfluid ouncesfl oz
gallonsgal
weightmetricgramsml
kilogramskg
Imperialouncesoz
poundslb
storage-kilobytesKB
megabyteMB
gigabytesGB
terabytesTB
month-JanuaryJan
FebruaryFeb
MarchMar
AprilApr
JuneJun
JulyJul
AugustAug
SeptemberSep
OctoberOct
NovemberNov
DecemberDec
week-SundaySun
MondayMon
TuesdayTue
WednesdayWed
ThursdayThu
FridayFri
SaturdaySat
time-weeksw
daysd
hoursh
minutesm
secondss
amount-thousandd
millionm
billionB

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
acronyms
  • Capitalize all letters
✅ Recommended usage❌ Deprecated usage
Create a new SLACreate 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 itemAdd 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 projectCreate a Project
2. Sentences starting with a number, the first letter does not need to be capitalized
✅ Recommended usage❌ Deprecated usage
2 results found2 Results found
3. A letter after a slash needs to be capitalized
✅ Recommended usage❌ Deprecated usage
Country/RegionCountry/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 livestreamingmaxattacks'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 minuteJust now
1–60 minutes13 minutes ago
Today10:30
YesterdayYesterday at 10:30
last 7 daysFriday at 10:30
7 days – 1 yearAug 14 at 10:30 08–14 10:30
more than 1 yearAug 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 dimensionEnglish format
second5sec / 5s
minute20min 5sec / 20m 5s
hour23hrs 8min 5sec / 23h 8m 5s
day3 days
week1 week
month3 months
year1 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 ase.g.
that isi.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:
  1. Go to "Settings"
  2. Choose "Create a user macro"
  3. 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
recommendednot recommended
  • 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 pm2:00 pm - 3:00 pm
Jan 15-Jan 31Jan 15-31
10-100 lb10 - 100lb
Jan 1-15Jan 1 - 15
4-5 days4 - 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 moonSun & 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–5223 – 52
Jan.14 – Feb.23Jan.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 "john@example.com"?Delete john@example.com?
"image 3234.png" failed to uploadimage 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/pluralSingle/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 profileEdit 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 generatedinsta-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