Overview
Consistent vocabulary creates a professional, predictable user experience. These standards apply to all user-facing text across the platform.
Why Vocabulary Matters
- Reduces cognitive load - users learn patterns once
- Enables accurate translation - clear meanings translate better
- Supports global audience - avoids idioms and cultural references
- Creates professional feel - consistent language builds trust
Voice Guidelines
The platform voice is friendly but professional, action-oriented, and globally accessible.
Writing Guidelines
- Friendly but professional tone
- Global audience awareness (no idioms or cultural references)
- Accessible language (participants are often non-professionals)
- Software should feel fun AND productive
- Action-oriented language (verbs over nouns)
- Title Case for buttons, sentence case for descriptions
Action Terms
Standard terms for user actions. Always use the preferred term.
| Term | Icon | Usage | Avoid | i18n Key |
|---|---|---|---|---|
New | Create new item from scratch | Create, Add | common.actions.new | |
Add | Attach to something existing | Create, New | common.actions.add | |
Edit | Modify existing item | Modify, Change, Update | common.actions.edit | |
Delete | Remove permanently | Remove, Trash, Destroy | common.actions.delete | |
Remove | Detach from context (can re-add) | Delete, Detach | common.actions.remove | |
Save | Persist changes locally | Submit, Apply, Store | common.actions.save | |
Submit | Send for processing/review | Send, Save | common.actions.submit | |
Send | Send message (chat context only) | Submit | common.actions.send | |
Cancel | Abandon in-progress action | Close, Discard, Abort | common.actions.cancel | |
Close | Dismiss UI (action may be complete) | Cancel, Exit | common.actions.close | |
View | Navigate to content | Open, Go to, See | common.actions.view | |
Show | Reveal content in place | View, Display, Expand | common.actions.show | |
Hide | Conceal content in place | Collapse, Minimize | common.actions.hide | |
Search | Find by text query | Find, Look for, Query | common.actions.search | |
Filter | Narrow by predefined criteria | Sort, Refine, Narrow | common.actions.filter | |
Duplicate | Create copy of item | Copy, Clone | common.actions.duplicate | |
Refresh | Reload current data | Reload, Update | common.actions.refresh | |
Export | Download data externally | Download, Save As | common.actions.export | |
Import | Load data from external source | Upload, Load | common.actions.import | |
Confirm | Acknowledge action | OK, Yes, Accept | common.actions.confirm | |
Continue | Proceed to next step | Next, Proceed | common.actions.continue | |
Back | Return to previous | Previous, Return | common.actions.back | |
Done | Complete flow | Finish, Complete | common.actions.done | |
Try Again | Retry after error | Retry, Redo | common.actions.tryAgain | |
Learn More | Link to documentation | Read More, Details | common.actions.learnMore |
State Terms
Standard terms for system states and feedback.
| Term | Usage | i18n Key |
|---|---|---|
Loading... | Data is being fetched or processed | common.states.loading |
Saving... | Changes are being persisted | common.states.saving |
Success | Operation completed successfully | common.states.success |
Error | Operation failed | common.states.error |
Warning | Attention needed, but not blocking | common.states.warning |
Info | Informational message, no action needed | common.states.info |
Key Distinctions
These terms are often confused. Use them correctly.
New vs Add
"New" creates from scratch. "Add" attaches to something existing.
"New Project" creates a project. "Add Participant" adds someone to an existing project.
Delete vs Remove
"Delete" is permanent destruction. "Remove" detaches from context (can be re-added).
"Delete Survey" destroys it. "Remove Tag" detaches but tag still exists.
Save vs Submit
"Save" persists data locally. "Submit" sends for processing or review.
"Save Draft" keeps work. "Submit Feedback" sends for review.
Cancel vs Close
"Cancel" abandons an in-progress action. "Close" dismisses UI (action may be complete).
"Cancel" on form discards changes. "Close" after success just dismisses dialog.
View vs Show
"View" navigates to content (new page/screen). "Show" reveals content in place.
"View Details" opens detail page. "Show More" expands content inline.
Search vs Filter
"Search" queries by text input. "Filter" narrows by predefined criteria.
"Search" takes free text. "Filter" uses dropdown options.
i18n Usage
All action terms are available in common.json. Use these keys for consistency.
Pattern
Always use the common.actions namespace for button labels.
// Always use common.actions namespace for button labels
import { useTranslations } from 'next-intl';
function MyComponent() {
const t = useTranslations();
return (
<div className="space-x-2">
<Button>{t('common.actions.save')}</Button>
<Button variant="outline">{t('common.actions.cancel')}</Button>
<Button variant="destructive">{t('common.actions.delete')}</Button>
</div>
);
}
// Server component example
import { getTranslations } from 'next-intl/server';
async function ServerComponent() {
const t = await getTranslations();
return (
<Button>{t('common.actions.new')} Project</Button>
);
}