Consistency Notes

It is important when working with lexicon entries to be consistent and grammatically accurate. This simple step goes a long way to improve development, translation and your end user's experience.

Here are a few things for your consideration:

• A phrase should be a complete thought. Do not use partial phrases. Passing another translated string in the middle of a single phrase is still a partial phrase. For example:
  • Incorrect — maketext('Your domain ') . $domain . maketext(' has been set up.')
  • Correct — maketext('Your domain [_1] has been set up.', $domain)
  • Correct — maketext('Your email account [_1] has been set up.', $email)
  • Incorrect — maketext('Your [_1] [_2] has been set up.',  'domain', $domain)
  • Incorrect — maketext('Your [_1] [_2] has been set up.',  'email account', $domain)
• If the text is a label or title that can be considered a complete thought, treat it as follows:
  • Correct —

    <h3>[% locale.maketext('Reseller Center') %]</h3>

  • Correct —

    [% locale.maketext('Domain') %] <input type="text" name="domain">

  • Incorrect —

    maketext('Your [_1] has been set up., maketext('Domain'))

• A phrase does not include formatting. This means that it should not contain padding whitespace, tabs, newlines, or markup of any kind. The UI-agnostic bracket notation method output can identify parts of a phrase that require a specific format.
• Use a true ellipsis (…) to express a part of a phrase. There are many rules that govern how ellipses should be used in various contexts. We are most likely to use an ellipsis when indicating a beginning and an end. For example:
  • Starting compile ...
  • ... Done!
  • When using an ellipsis, take heed of the following:
    • An ellipsis is always 3 dots.
    • Please include a single space on either side of the ellipsis.
    • Look up the proper usage if you are unsure of the way an ellipsis should be used in a given context.
    • We could standardize on the ellipsis character. However, this can be problematic as, generally, people do not know how to enter one without looking it up. Using the ellipsis character in a key can make it difficult to distinguish the difference between the ellipsis character and 3 dots. For example, the strings below are not the same and one would not map to the other during lookup:
      • Starting compile …
      • Starting compile ...
• Use Oxford commas and concise language to avoid ambiguity. For example:
  • Correct — I like orange, green, and blue.
  • Incorrect — I like orange, green and blue.
• Acronyms should always be expressed in capital letters.
• Avoid colloquialisms and vernacular where possible.
• Avoid puns and other wordplay. Again, you should always use precise language.
• When using a colon (:) to introduce something, use a single space after the colon. For example:
  • Your current locale is set to: [_1].
  • Could not open '[_1]' for reading: [_2].