Content conventions
An editorial contract for English interface copy, with examples, localization handoff and explicit exceptions for source text.
Scope and ownership
Apply these conventions to authored interface strings. Quotations, names, dictionary entries, archival transcriptions and community-approved wording retain their recorded spelling and punctuation. A style preference cannot silently edit evidence. Keep an original value and provenance when an authorized editorial rendition is needed.
English conventions are a starting contract for this interface, not rules for every language. Translators own locale-specific grammar and punctuation with appropriate review. Record an exception’s reason, owner and affected messages; never run a global replacement over source records.
Consequences and scannable structure
Place the decision and its effect together. Distinguish saving a draft, sending a request and publishing to readers. If an operation can be reversed, describe the actual recovery path; if it cannot, state that before activation. A neutral explanation gives a person enough information to decide without pressure.
- Give each section a descriptive heading and one task. Put the next action near its explanation.
- Move background detail to help or a destination while keeping the immediate consequence visible.
- Test the wording with context hidden and with text enlarged; apparent brevity is not comprehension.
| Situation | English interface example | Verify |
|---|---|---|
| Local draft | Save draft — keeps this text on this device | Actual storage and recovery match the claim |
| Publication decision | Publish revision — readers will see this revision | Audience, permission and exact revision are established |
| Failed search | Search did not finish. Your query is still here. | Retained query and usable retry exist |
| Empty filtered list | No results with these filters. Change filters. | This is the searched scope, not a claim about the whole language |
Capitalization and abbreviations
Do not use CSS text-transform to manufacture a spelling change. A source entry can contain meaningful case distinctions. Keep visible labels aligned with accessible names and use the same action wording in help.
| Concern | Local convention | Exception or failure |
|---|---|---|
| Interface labels | Use sentence case: Review source details | Preserve approved names and source capitalization |
| Abbreviations | Prefer Recording duration to Rec. dur. | A necessary familiar acronym still needs context |
| First use | Introduce an unfamiliar term with its full name | Do not repeatedly expand a term in every action label |
| Short surfaces | Change hierarchy or supply nearby help | Do not remove a review qualification to fit |
| Emphasis | Use hierarchy and explicit wording | Uppercase blocks and punctuation are not status semantics |
Pronouns and the speaking role
Keep the speaking role coherent within a flow. A heading in the product’s voice and a checkbox representing the person’s preference can legitimately differ; a single sentence should not drift between them. Avoid “we approved this” unless the responsible group and review are real. Do not imply ownership from a logged-out session, locale or name.
| Role | English example | Decision |
|---|---|---|
| Person’s task | Your draft remains available | Use direct address when ownership is established |
| Product operation | The request did not finish | Name the system event instead of implying human fault |
| Record status | Review status unavailable | A missing reviewer is not a collective “we” |
| Personal option | Save this draft on my device | First person may suit an explicitly personal setting |
| Action command | Save draft | An imperative often needs no pronoun |
Periods, contractions and lists
Choose consistency within a set of list items: parallel phrases or complete sentences. Do not remove punctuation from an actual quotation to match the surrounding UI. Contractions are a tone choice, not an automatic shortening rule for legal, permission or translated content.
| Surface | Convention | English example |
|---|---|---|
| Short label or heading | Usually no terminal period | Recording settings |
| Complete help sentence | Use normal sentence punctuation | Choose a permitted recording. |
| Multi-sentence message | Separate complete thoughts clearly | The request stopped. Your draft remains available. |
| Contraction | Use a familiar form when its meaning is clear | You can’t publish without permission. |
| Ambiguous contraction | Write the intended meaning explicitly | The source has changed, rather than Source’s changed |
| List in a sentence | Use a serial comma when it clarifies grouping | Check the source, audience, and review status |
Numbers, counts and regional formats
Store counts as numbers and format them for the selected interface locale. Keep identifiers as identifiers: a source accession number must not acquire grouping separators. Choose precision from the measurement and task; rounding must not imply unsupported accuracy.
English count messages need the singular form at one. Other locales can require more categories; use complete translated messages with plural/select support rather than concatenated fragments. Zero should explain the current scope and a useful next step.
| Value | English example | Meaning |
|---|---|---|
| 0 | No queued notices | Current queue is empty |
| 1 | 1 queued notice is available | One actual local record |
| 2 | 2 queued notices are available | Two actual local records |
| 1,000 | 1,000 results | Locale-formatted count, not an identifier |
| Decimal | 1.5 seconds | Explicit unit and measured precision |
// English-only message fixture; keep other locales in complete plural messages.
const message = count === 1
? "1 queued notice is available"
: `${new Intl.NumberFormat("en-AU").format(count)} queued notices are available`;
// count must be a verified nonnegative integer.
// Never use this English branch as a multilingual plural implementation.Colons, exclamations and ellipses
Punctuation does not create an accessible state. A loading control still needs its busy/disabled and cancellation behavior. Keep an omission in source material distinguishable from an author’s prose and link the full source.
| Mark | Use | Failure to avoid |
|---|---|---|
| Colon | Introduce an actual definition or list in prose | Decorative terminal colons on every heading |
| Exclamation | Use sparingly when an appropriate verified event warrants it | Celebrating an unresolved error or demanding consent |
| Ellipsis | Represent omitted quoted material accurately or an established action convention | Pretending repeated dots prove progress |
| Loading | Name the operation and expose its actual state | Relying on punctuation animation as the only loading indicator |
Parentheses, ampersands, dashes and hyphens
Do not hide permission, retention or uncertainty in a long parenthetical aside. Avoid automatically joining words with hyphens to invent product terminology. Preserve punctuation inside names, quotations and language entries. A typography replacement must not change an identifier or executable code.
| Choice | Local treatment | English example |
|---|---|---|
| Parentheses | Use for a brief secondary definition; keep essential constraints outside | Portable Document Format (PDF) |
| Ampersand | Prefer “and” in authored prose; retain an official name as recorded | Source and review |
| Dash | Use a normal sentence or explicit relationship when that reads more clearly | Your draft is saved. Publication is still pending. |
| Hyphen | Use when established spelling or grammar requires it | Keep an approved name’s recorded hyphen |
| Minus sign | Treat numerical meaning separately from prose punctuation | A negative measurement is not a decorative dash |
Italics, emphasis and accessible meaning
Use emphasis to support a readable sentence rather than to encode the only instruction. Keep a qualification written explicitly; italic text or color alone cannot distinguish verified and unverified records. Long italic passages and uppercase blocks make scanning harder.
Use semantic emphasis when the change of meaning calls for it, not merely to approximate a font style. Verify the actual font’s italic glyph coverage and fallback. Read text without its styling to check that the task and status remain understandable.
Reference conventions and deliberate project exceptions
These are explicit local writing choices and comparison points, not an automatic grammar transformer or a claim that every project convention reproduces Material verbatim. Localized content needs its own writing and review policy.
| English reference point | Local decision | Reason/scope |
|---|---|---|
| Periods on single-sentence surfaces | Material omits them on many compact surfaces; this guide uses normal punctuation in complete explanatory sentences | Keep each surface consistent and document exceptions; source quotations retain their original punctuation. |
| Quotation commas | Material places commas inside English quotation marks; localized authored copy follows its agreed policy | Do not silently rewrite source text, code or a quoted identifier. |
| Millions and approximation | A compact 1.2M may suit a broad overview; exact data remains available | Format for locale and disclose rounding; do not abbreviate an accession number. |
| Ellipsis placement | No leading space; omit decorative command ellipses | Actual CSS truncation requires full-content access; dots do not prove progress. |
| Ranges and hyphen function | Use an agreed range separator and distinguish a noun such as check-in from the verb check in | An established grammatical spelling differs from an invented product compound; preserve recorded names. |
| Pronoun consistency | Use a coherent speaking role; explicitly personal acknowledgments may use first person | Do not impersonate a reviewer/group or mix ownership inside one message. |
Editable editorial preview
Use the existing message lab to revise the heading, explanation and action together. Compare a singular count, a retained-draft failure and a permission consequence. The action changes local demonstration status; it sends no request.
The lab previews authored text and layout. It does not score grammar, infer cultural authority or automatically rewrite source wording. Keep editorial judgment with the responsible people.
Search did not finish
Your search text is still here. Check your connection and try again.
Edit and assess the copy yourself. This is a layout preview, not automated language review or an actual failed request.
Implementation and localization handoff
- Keep interface strings apart from source fields. Record message key, surface, speaking role, variable meanings and actual outcome.
- Provide screenshots and complete messages, including empty, singular, plural, delayed and failure states. Do not translate detached sentence fragments.
- Format numbers and dates with an explicit locale/time zone policy; never reconstruct storage values from localized display text.
- Keep a stable accessible action name. Test visible wording, computed name, help and resulting status together.
- Review substitutions with long names, punctuation, mixed direction and combining marks. Render text as text, not interpreted markup.
- Use a message catalog and translation tooling in the consuming application. This English documentation fixture is not a deployed multilingual message catalog.
Editorial verification and exceptions
- Follow a real task from decision through completion or recovery. Compare every verb and tense to the actual state.
- Review zero, one and many counts; missing variables; pending requests; and stale reopened messages.
- Check labels without the body, then check the full reading order. A shortened label must still identify its action.
- Inspect both themes, narrow layouts, enlarged text, keyboard operation and accessible names.
- Have the responsible translator/reviewer assess localized wording and permitted source content. Layout checks do not approve meaning.
- Record any exception with its surface, reason and owner. Preserve source evidence rather than applying interface conventions to it.