Status: Accepted v1.0
Owner: OSHUN Design + Product + Engineering
Last Updated: March 26, 2026
Implements: V1-UX-067
Related:
docs/releases/v1/design/readability-standards.mddocs/releases/v1/scope/scan-first-content-hierarchy-rules.mddocs/releases/v1/specs/tara-content-tone-standards.mddocs/releases/v1/specs/veritas-content-tone-standards.mddocs/releases/v1/specs/nisaba-content-tone-standards.mddocs/releases/v1/design/ai-disclosure-copy-guidance.mddocs/releases/v1/design/error-outage-and-fallback-copy-guidance.mddocs/releases/v1/specs/studio-internationalization-and-localization-dependency-and-data-contract-map.mdapps/oshun/mobile/src/i18n/strings.tsapps/oshun/web/src/i18n/config.tsapps/oshun/web/src/i18n/formatting.tsapps/oshun/web/src/components/LanguageSwitcher.tsxdocs/releases/v1/specs/todos.md
1. Purpose#
This document defines the canonical rules for compressing UI copy in OSHUN V1 so interface text stays:
- concise
- specific
- scannable
- localizable
- resilient under text expansion
The goal is not to make OSHUN sound clipped or robotic.
The goal is to remove waste so the remaining words still communicate clearly after translation, reflow, dynamic type, and right-to-left layout.
2. Current Repo Signals, External Scan, And Gap#
The current repo already establishes several strong constraints:
READABILITY_STANDARDS.mdalready requires support for dynamic text scaling, no clipping, and30-50%localization expansion in labels and buttons.OSHUN_V1_SCAN_FIRST_CONTENT_HIERARCHY_RULES.mdalready sets concise label targets, rejects placeholder-only naming, and treats headings, actions, and helper text as different hierarchy jobs.- Tara tone guidance already says headings should usually stay within
2-5words and supporting copy should usually be one short sentence. - Error and disclosure copy guidance already favors short titles, direct body text, and plain vocabulary over decorative or defensive writing.
apps/oshun/mobile/src/i18n/strings.tsalready centralizes a large portion of shell copy in one catalog instead of scattering strings across components.apps/oshun/web/src/i18n/config.tsalready declares a multi-locale target set includingarfor RTL handling.apps/oshun/web/src/i18n/formatting.tsalready uses locale-aware date, time, number, currency, and list formatting rather than English-specific string assembly.- the Studio localization contract already includes
ci_expansion,expansionViolationCount, and RTL validation as first-class release signals.
External implementation guidance points in the same direction:
- Microsoft’s current localization writing guidance says easy-to-read content is easier to localize, recommends short simple sentences, lists instead of dense paragraphs, verbs in short labels when clarity requires them, and consistent terminology for each concept.
- Microsoft also explicitly warns against idioms, modifier stacks, sentence fragments that reduce clarity, and synonym drift for the same feature.
- USWDS guidance says interface copy should be clear, focused, concise, written in plain language, and biased toward short sentences and straightforward wording.
- Android and Apple both recommend pseudolocalization to test whether layouts can absorb longer strings before translation ships.
- Android’s localization tooling also distinguishes truly untranslatable strings such as product names or trademarks from ordinary UI copy.
Inference from those sources plus the repo state:
- OSHUN already knows it must support expansion and multiple locales.
- OSHUN does not yet have one explicit rule set telling teams how to compress source-English copy so those localization budgets remain viable across buttons, headings, helper text, notifications, and operator surfaces.
3. Canonical Thesis#
Compress the wording, not the meaning.
OSHUN copy compression means:
- fewer words
- less drift
- less duplication
- stronger terms
- layouts that still work when translated
It does not mean:
- vague labels
- generic actions
- unexplained abbreviations
- removing the one word that carries the real consequence
The ideal compressed string is shorter because it is sharper, not because it is missing the hard part.
4. Core Rules#
4.1 One String, One Job#
Each UI string should carry one primary job:
- orient
- label
- instruct
- confirm
- warn
- recover
If one string tries to explain the page, justify the policy, and tell the user what to do next, it is too long.
4.2 Prefer Specific Words Over Extra Words#
Good compression comes from stronger nouns and verbs.
Prefer:
RetryQueued actions pendingSignoff notesSaved for later
Over:
Try again nowThere are queued actions that are still pendingNotes related to the signoffThis item has been successfully saved for later review
4.3 One Product Concept Gets One Term#
Use the same word for the same concept across the product.
Examples:
Saveshould not alternate casually withBookmark,Store, andKeep for later.Changes requestedshould not alternate withNeeds editsunless the workflow genuinely defines different states.Synthetic voiceshould not alternate withAI voice actororgenerated voice.
Compression fails when synonym drift forces the user to re-learn the same concept in different places.
4.4 Write For Translation, Not Just For Native English#
Avoid:
- idioms
- slang
- puns
- culture-specific references
- metaphor-heavy action labels
Also avoid stacked modifier phrases such as:
high-priority runtime queue approval staterapid-release emergency policy override workflow
Break the idea into a heading plus structured labels instead.
4.5 Break Dense Sentences Into Lists Or Paired Lines#
If the English source needs multiple commas, and, or, or but to stay
grammatical, it probably needs structural compression instead of copy edits.
Preferred replacements:
- bullet list
- field group
- metadata row
- title plus short support line
4.6 Use Fragments Carefully#
Fragments are acceptable for:
- tabs
- chips
- compact labels
- short state badges
Prefer full sentences when the copy explains:
- recovery
- consequence
- safety limitation
- blocking error
4.7 Compression Must Preserve Accessible Clarity#
Do not compress visible or assistive copy so far that the control becomes ambiguous.
Bad compression:
Do itOpenGoMore
unless the surrounding object and screen structure already make the outcome unmistakable.
5. Source-English Compression Budgets#
These are review thresholds for source English, not universal hard caps.
If a string exceeds them, the author should justify the length or redesign the layout.
5.1 Labels, Tabs, Chips, And Segmented Controls#
Preferred target:
1-3words- usually one line at launch widths
Review closely when:
- the label exceeds
16source characters - the concept needs punctuation to make sense
- the label wraps before localization
5.2 Buttons And Primary Actions#
Preferred target:
1-4words- one clear verb
Review closely when:
- the action exceeds
24source characters - the label contains more than one clause
- the label repeats context already visible in the heading
5.3 Field Labels#
Preferred target:
1-5words
Review closely when:
- the label is longer than the field value it describes
- helper text is carrying the true label meaning
- the label contains policy explanation instead of field naming
5.4 Titles And Headings#
Preferred target:
2-6words- no more than
2lines above the fold
Review closely when:
- the title exceeds roughly
55source characters - the title contains both orientation and explanation
- a subtitle is required just to decode the title
5.5 Helper Text, Empty-State Bodies, And Toast Bodies#
Preferred target:
- one short sentence
- one idea only
Review closely when:
- the copy exceeds
2clauses - the message repeats the title
- a list would communicate the detail more efficiently
6. Localization Expansion Rules#
6.1 Design For 30-50% Expansion By Default#
English source copy should usually consume no more than about 70% of the
available width budget in compact controls.
If the English source already fills the full available line, the design or the copy is not ready for translation.
6.2 Short English Strings Are Not Always Safe#
One-word or two-word English strings can expand sharply in translation.
Do not assume:
SaveDoneLaterQueued
will remain equally short in every locale.
6.3 Pseudolocalization Is Mandatory For Risky Surfaces#
Before signoff on new or revised UI copy, expansion-sensitive surfaces should be checked with pseudolocalization or equivalent expansion testing, especially for:
- nav labels
- tab bars
- button groups
- form labels
- compact tables or queue rows
- sticky action bars
6.4 RTL And Reordering Must Stay Viable#
Do not build copy patterns that assume English word order, left-to-right icon placement, or sentence fragments assembled by concatenation.
Localized strings must be able to reorder naturally.
7. String Construction Rules#
7.1 Do Not Concatenate UI Fragments Into English-Only Sentences#
Avoid constructing messages like:
Saved+ objectName +successfullyYou have+ count +pending items
Prefer full-message templates with variables so translators can reorder the sentence naturally.
7.2 Keep Data Formatting Out Of Literal Copy#
Dates, times, numbers, percentages, currencies, and lists should come from the locale-aware formatting layer rather than custom English copy.
This preserves compression and translation quality at the same time.
7.3 Mark Only Truly Untranslatable Terms As Fixed#
Product names, trademarks, canonical domain names, and approved technical terms may remain untranslatable when necessary.
Do not freeze ordinary UI text in English just because the shorter English string fits the layout better.
7.4 Provide Context For Ambiguous Short Strings#
Short strings such as:
SaveReviewArchivePending
need translator context when the intended meaning is not obvious from the key alone.
Compression without context creates translation drift.
8. Pattern-Specific Rules#
8.1 Titles And Subtitles#
The title should name the object or state.
The subtitle should add only what the title cannot.
Bad:
- title:
Manage your language preferences and notification settings - subtitle:
Use this page to update the language you want and how often you hear from us.
Better:
- title:
Language and notifications - subtitle:
Choose your language and delivery preferences.
8.2 Buttons And Action Labels#
Prefer direct verbs:
RetrySync nowSave changesRequest changes
Avoid:
ProceedTake actionComplete this step now
unless the surrounding step container already resolves the ambiguity.
8.3 Helper Text#
Helper text should explain:
- requirement
- format
- consequence
- limit
It should not restate the label in longer words.
8.4 Empty, Error, And Status States#
Use the shortest structure that still answers:
- what happened
- what it means
- what to do next
Default pattern:
- short title
- one-sentence body
- one dominant action
8.5 Dense Admin And Table Surfaces#
On operator surfaces, compress by moving detail into structure:
- columns
- badges
- metadata clusters
- helper rows
Do not convert everything into sentence-form explanatory copy.
9. Explicit Anti-Patterns#
These patterns are non-canonical for OSHUN V1:
- headings that read like campaign copy
- action labels that need the whole screen to make sense
- filler openings such as
Use this page to... - filler confirmations such as
Your request has been successfully... - duplicate title and body copy in toasts, alerts, and empty states
- string concatenation that fixes English word order
- unexplained abbreviations added only to save space
- compressing copy while leaving the layout over-constrained
- freezing ordinary strings as English-only to avoid localization reflow
10. Acceptance Criteria#
OSHUN copy compression is correct only when all of these are true:
- the source string is shorter because it is more specific, not because it is less truthful
- the string still makes sense when read out of full-page context
- the layout preserves room for
30-50%expansion - pseudolocalization or equivalent expansion checks pass on compact surfaces
- terminology stays consistent across customer and operator surfaces
- formatted dates, times, numbers, and lists come from locale-aware utilities
- ambiguous short strings have sufficient implementation context for translators
11. Delivery Checklist For Coding Agents#
When adding or revising OSHUN UI copy:
- shorten by removing duplication before removing meaning
- check whether a list, badge, or field group can replace a long sentence
- keep source English within the review thresholds above where feasible
- store strings in catalogs or stable message definitions rather than ad hoc concatenation
- use locale-aware formatting helpers for numbers, dates, times, currencies, and lists
- verify compact controls under expanded or pseudolocalized text before signoff
- leave translator notes or clearer keys when a short label could be ambiguous