UI Text Guidelines

This document helps designers, developers, and translators learn about making UI Text (such as labels, headings, and messages) effective and consistent across the platform.

Table of Contents

• Approach
• General Rules
• Translation Constraints
• Component-Level Rules
• English Grammar Rules

Approach

Keep it short and to the point:

• Simplify sentences and use shorter words, without compromising the meaning.
  • E.g. use “Go to” instead of “Navigate to”.
  • E.g. use “Campaign was created” instead of “Campaign has been created in your account”.
  • You can omit the UI component's name, e.g. use "Click Save" instead of "Click Save Button".
• UI text should be simple and short not to save space, but to make the UI easier to read.
• Avoid using redundant words.
  • E.g. use “Create Campaign” instead of “Create New Campaign”.
• Use tooltips to hide explanations.

Aim for consistency by following the guidelines:

• Always try implementing what’s documented, even if other parts of the product might not follow it. Some of the UI might be outdated, while the documentation has the latest guidelines.
• If something is missing from the Emarsys documentation, check the SAP documentation.
• When something is not documented, then try using other Emarsys pages as reference. In this case, please notify the Design System team about the missing documentation.

English first:

• We use English as the default language for our products. Translations are made based on the English text.

Expect longer text when translated:

• Translated text might be longer or shorter than the original English text, so make sure the layout can adapt.

Know how “translation strings” work:

• Knowing the technology and workflow behind how we translate from English to different languages can help writing text that’s easier to translate.
• For translation constraints, see below.

General Rules

Abbreviations:

• Avoid using non-standard abbreviations, like VCE, VCMS, SI.
• Industry standard abbreviations can be used, like AOV, but explain them on the UI, like in a tooltip or in a helper message.
• Avoid latin abbreviations, use full form instead:
  • “e.g.”: for example
  • “i.e.”: that is
  • “etc.”: and so on
  • “n.b.”: note
  • “et al.”: and others
  • “vs.”: opposed to, versus
  • “cf.”: compare

Symbols:

• Avoid using symbols like “&”, “/”, “+” for shorthands of words in sentences, use “and”, “or”, “plus” instead.
• Avoid semicolons (;), use separate sentences instead.

Messages:

• Confirmation messages:
  • Avoid lengthy titles.
    • E.g. instead of “Are you sure you want to delete this campaign?”, use “Delete campaign?”.
• Error messages:
  • Avoid generic error messages.
    • E.g. “Something went wrong”.
  • Specify the error when possible.
    • E.g. “Couldn’t establish a connection with the server”.
  • Propose solutions when possible.
    • E.g. “Couldn’t establish a connection with the server. Please try again in a minute.”.
• Success messages:
  • Avoid redundant “successfully” or “success”.
    • E.g. use “File uploaded” instead of “File uploaded successfully”.

Formatting with utility components:

• Numeric component. Can display "10000000" as "10,000,000".
• Currency component. Can display "256" as “$256”.
• Time component. Can display “2018-03-22T14:39:15.087” as other date and time formats.

Breadcrumbs and access paths:

• When referencing an access path inside Emarsys, separate the path by “>”.
  • E.g. Channels > Emails

Positive formulations:

• Use positive formulations in checkboxes, switches.
  • E.g. Use “[✓] Enable this feature” instead of “[✓] Disable this feature”.

Text style formatting (bold, italics, underline, uppercase):

• Avoid using text formatting like bold and italic to convey meaning or semantics.
• Avoid using uppercase.
  • Uppercase is reserved for certain not-translatable technical expressions. E.g. AND, OR
• Links should be underlined in sentences.

Product names, “trademark” feature names:

• Use title case for products, features, and asset types that have specific meaning in the context of Emarsys.
  • E.g. Measurement Node, Empty Cart Tactic
  • E.g. Tactics, Home, Strategic Dashboard, Smart Insight, Predict

Active voice and passive voice:

• Use active voice in actions, like button labels and instructions.
  • E.g. Use “Upload your data” instead of “the data needs to be uploaded”
• Use passive voice when describing a situation, like in error messages.
  • E.g. “File not found”

Tenses:

• If there was an error in the past, but it can be fixed, use past tense for the error.
  • E.g. “File was not found. [Search Again]”
• If there is a persistent error that cannot be fixed, use present tense.
  • E.g. “File cannot be found.”
• Use simple past tense instead of present perfect tense, as it’s shorter and easier to understand for non-native speakers.

Noun phrases vs verb phrases:

• In page titles and headings, use noun phrases (“Content Creation”) instead of verb phrases (“Create Content”).

Titles and headings:

• Titles should always be Title Case (in English).
• Make titles as short as possible, aim for less than 5 words.
  • If the title becomes more than 5 words, simplify it by describing information in inline text, helper message, Tooltip, Notification.
• Avoid redundant words in headings that’s already present in the page title.
  • E.g. In the “Email Settings” page, instead of “Email Sender Settings” use “Sender Settings”.

Visual navigation:

• Avoid referring to content or UI elements by their location on the screen, as future changes in the layout might break these references.
  • E.g. instead of “Click the button at the top right”, use “Click Save”.

Avoid using the term "country":

• For legal reasons, do not use "Country", use "Country or Region" or another term that works in the given context, like "Market".

Translation Constraints

Translation strings: individual, translatable content. The strings appear as placeholders in the UI code instead of actual UI text. These strings are replaced with a translation based on the user’s preference. For example, the string {saveButtonLabel} will be replaced by the translated text “Save” in English, and by “Mentés” in Hungarian.

Variables: text that don’t come from translations, but from content, like the title of an email campaign, or a date set by the user.

Avoid putting grammatical rules in variables:

• E.g. instead of “Start the program {in the morning}”, use “Start program: {morning}”, so the variable won’t have grammatical rules (“on”), making it easier to translate.

Avoid string fragmentation:

• Translation strings should be as self-contained as possible, otherwise translators won’t have the proper context.
  • E.g. Instead of {Uploaded on:} {Date-Time}, use {Uploaded on: {Date-Time}}
• As not all components can be easily turned into text placeholder that translators can move around without breaking the UI, insert components at the end of sentence, separated from the text.
  • E.g. Instead of {Wait {Number Input} days before re-entry}, use {Number of days before re-entry: {Number Input}}.

Avoid marking plurals with “(s)”:

• Some languages have multiple forms for plural, or they solve plurals without suffixes.
• Alternatives:
  • Separate strings for singular and plural cases
    • E.g. “File uploaded” for singular case, “Files uploaded” for plural case.
  • Use plurals only.
    • E.g. “Change the contracts.”
  • Use “One or more” in front of the plural noun.
    • E.g. “Create one or more backup files.”
  • Use “Noun or nouns”
    • E.g. “Select the region or regions for the sales revenue report.”
  • Use “each”, “every” or “any of”:
    • E.g. instead of “Drag the file(s) to the relevant folder(s)”, use “Drag each file to the relevant folder”.
  • Disconnect number from noun:
    • E.g. Instead of “{n} file(s) were deleted”, use “Number of deleted documents {n}”.

Use descriptive string names:

• Translators might only look at the text, without the screens.
• Translators are helped by any context. If possible use descriptive string names (placeholders). You and the developers know about the purpose of the string name, the translator might not.
  • E.g. Instead of “Created on: <stringone>”, use “Created on: <datetime>”

Include punctuation in translatable strings:

• Punctuation (periods, commas, colons, hyphens, etc.) should be included in the translatable string, so translators can see the whole context.
  • E.g. Instead of “<Created on>: <datetime>”, it should be “<Created on:><date>”
  • E.g. Instead of “<Good Morning>, <name>!”, it should be “<Good morning, <name>!>”
• Other languages might use punctuation differently (like in French, they put a space before colons).

Component-Level Rules

Button labels:

• Simplify and shorten labels as much as possible.
  • E.g. use “Upload File” instead of “Upload the File”.
• Button labels should describe the action, not a response
  • E.g. “Delete This Campaign?”, use “Delete” instead of “OK” or “Yes”.
• Use “Close” instead of “OK” as the button text for closing an error message.
• Use “OK” if the user is just acknowledging a piece of information or a group of settings.
• Buttons that navigate the user should also imply the action, e.g. instead of just “Detailed View”, it should be “Go to Detail View”, or “View Details” (use active imperative formulation).
• When pressing the button results in multiple actions, avoid using multiple labels, and use the most prominent action as the label.
  • E.g. use "Save" instead of "Save and Apply", use "Discard" instead of "Discard and Leave".
  • Exception: when it's critical to emphasize multiple actions.

Inputs labels:

• “Labels” are input field labels, switch labels, checkbox labels, radio labels, column labels, tab labels, etc.
• Use title case for labels.
• Simplify and shorten labels as much as possible. If the label “needs to be long”, try using a short label with a tooltip or a helper message, where longer text can be displayed.
• Don’t put colon at the end of the label
  • Exception: use colon when the label is next to the field, in a horizontal layout (but avoid horizontal layout in general).

Input placeholder texts:

• Placeholder text mainly helps the affordance of interactive elements, i.e. makes it apparent for the user that the input field can be typed into. But proper labeling and contextual messages are more important than placeholder texts.
• Should be a command what the user should do in this field
  • E.g. “Search” text input field: “Type search keywords here”
  • E.g. “Audience” select: “Choose recipient list”
  • Don’t forget that “please” is reserved for inconvenient situations for the user. We use it in sentences when we ask the user to do something other than the usual flow. (Please restart the procedure.)
• If the input expects a specific format, then it can contain an example (either instead of the command, or next to the command)
  • E.g. “Email” input field: “For example: john.doe@gmail.com”
  • E.g. “Phone number” input field: “Enter phone number, for example: +36 30 5432 109”
• Do not replace field labels with placeholders.
• Do not put validation-critical text in placeholder.
  • If the input format is validation-critical (like password requirements), it should be visible close to the input field, not in the placeholder.
• Use incomplete sentences: sentence case, with no punctuation at the end.

Radio button options and Checkbox options:

• Options can be either labels (short, Title Case) or sentences (longer, Sentence case) depending on the content. Don't mix the two kinds in the same list, though!
• For options with sentences, use the incomplete sentence rules: no punctuation, unless it's multiple sentences.

Tables:

• If a table column contains multiple values, separate them with slash. Follow and precede slashes with a space.
  • E.g. “Country / Language”: “HU / HU”
• Plurality rule:
  • Use the singular in the column heading if there is only one entry per table row.
    • E.g. “Tags”: “Tag1, Tag2, Tag3”
    • E.g. “Category”: “Email Campaign”
• Empty values:
  • When data doesn’t exist for a field, display “No Data” or “N/A”. If we know what type of data is missing, we can include that as well, like “No Description”, “No Title”, etc.
  • Don't use values like “0” in place of “Not Available”.

Learn more links / Helper link component:

• Links should adapt to their context, based on where they’re used:
  • When used in a complete sentence as a link, use sentence case with punctuation.
  • When used in an incomplete sentence as a link, use sentence case without punctuation.
  • When used as a button, use title case.

Tooltips:

• If the tooltip contains inline text content, then use sentence case.
• If it replaces a button label (like for icon buttons), then use title case.

Notifications:

• Use past tense for error notifications.
  • E.g. “File Not Found”

Empty States:

• Use present tense empty states.
  • E.g. “No Data Available”

English Grammar Rules

Plurality:

• When a label refers to a single item, use singular (e.g. “Name” in table header).
• When a label might refer to multiple items, use plural (e.g. “Select items”).
• In messages, have different messages for plural and singular results (e.g. “You have 1 day to do this” vs “You have 2 days to do this”). Avoid the “(s)” to make plurality conditional.

Case:

• Title case:
  • Use title case for short incomplete sentences, like titles, headings, column headings, and labels.
  • Don't use punctuation.
  • This utility can help convert sentences to title case: https://www.titlecase.com/.
• Sentence case:
  • Use sentence case for inline text, like messages, notifications.
  • For complete sentences, use proper punctuation.
  • For incomplete sentences (shortened sentences that contain no subject or predicament):
    • Single sentence:
      • Don’t use punctuation.
    • Multiple sentences:
      • Use punctuation for each incomplete sentence.

Quotations:

• Use quotation marks to highlight user-made resource names in a sentence.
  • E.g. Notification: Your program “myfavouriteprogram” was distributed to account “Testaccount1”.
• Use quotation marks to refer to values.
  • E.g. You can enable STO in a program if its status is “In Design”.
• Use quotation marks to refer to other sentences, which would be syntactically confusing to include in the sentence.
  • E.g. Check "I have read and agree to the terms and conditions" to continue.

Contractions:

• Use contractions like "can't", "don't", "isn't", etc. to make the text sound friendlier.
• Do not use a contraction if you want to emphasize the verb.
  • E.g. use "Do not leave this page while the process is running" instead of "Don't leave this page".
• Avoid using contractions with multiple meanings like "you'd" (it can be both "you had" and "you would").

Further English grammar rules:

• “Because of” vs “due to”.
  • “The upload failed because of an incorrectly formatted file.” (after verb)
  • “The upload failure was due to an incorrectly formatted file.” (after noun)