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 | Creating something from scratch | Create | common.actions.new | |
Add | Adding to an existing collection | New, Create | common.actions.add | |
Edit | Modifying existing content | Modify, Change | common.actions.edit | |
Delete | Permanently removing something | Remove | common.actions.delete | |
Remove | Detaching from a collection | Delete | common.actions.remove | |
Save | Persisting changes (remains editable) | Submit | common.actions.save | |
Submit | Finalizing and sending for processing | Save, Send | common.actions.submit | |
Send | Transmitting to someone | Submit | common.actions.send | |
Cancel | Aborting an in-progress action | Close | common.actions.cancel | |
Close | Dismissing a UI element | Cancel, Dismiss | common.actions.close | |
View | Viewing content in detail | See, Show | common.actions.view | |
Show | Revealing hidden UI elements | View, Display | common.actions.show | |
Hide | Concealing UI elements | Close | common.actions.hide | |
Search | Finding specific items by query | Find | common.actions.search | |
Filter | Narrowing results by criteria | Search | common.actions.filter | |
Duplicate | Creating a copy | Copy | common.actions.duplicate | |
Refresh | Reloading current data | Reload | common.actions.refresh | |
Export | Saving data externally | Download | common.actions.export | |
Import | Loading data from external source | Upload | common.actions.import | |
Confirm | Approving an action | OK, Yes | common.actions.confirm | |
Continue | Proceeding to next step | Next | common.actions.continue | |
Back | Returning to previous step | Previous | common.actions.back | |
Done | Completing a workflow | Finish, Complete | common.actions.done | |
TryAgain | Retrying a failed action | Retry | common.actions.tryAgain | |
LearnMore | Accessing additional information | More Info | 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 something from scratch. "Add" attaches something to an existing collection.
Use "New Program" to create one, "Add Member" to include someone.
Delete vs. Remove
"Delete" permanently destroys. "Remove" detaches from a collection but doesn't destroy.
Use "Delete Program" to destroy it, "Remove Member" to disconnect them.
Save vs. Submit
"Save" persists changes (you can keep editing). "Submit" finalizes and sends for processing.
Use "Save Draft" for in-progress work, "Submit Feedback" to finalize.
Cancel vs. Close
"Cancel" aborts an in-progress action. "Close" dismisses a UI element without aborting.
Use "Cancel Upload" to abort, "Close Dialog" to dismiss.
View vs. Show
"View" opens content for inspection. "Show" reveals hidden UI elements.
Use "View Details" to inspect, "Show More" to reveal hidden content.
Search vs. Filter
"Search" finds specific items by query. "Filter" narrows results by predefined criteria.
Use "Search Projects" to query, "Filter by Status" to narrow.
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
function MyComponent() {
return (
<div className="space-x-2">
<Button>{"Save"}</Button>
<Button variant="outline">{"Cancel"}</Button>
<Button variant="destructive">{"Delete"}</Button>
</div>
);
}
// Server component example
import { getTranslations } from 'next-intl/server';
async function ServerComponent() {
const t = await getTranslations();
return (
<Button>{"New"} Project</Button>
);
}