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 points to consider:

• First, make sure there is no existing phrase that says what you want to say.
• 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)
• Do not use bare variables, for the following reasons.
  1. They promote partial phrases.
     • For example, if you have the following phrase: Your username [_1] is set up. a user will be tempted to write: mt('Your username [_1] is set up.', mt('was configured'))
  2. They are clearer when dealing with values. Example: The new value is [_1].
     • When the new value is an empty string, the phrase will not make sense: The new value is .
     • But, if the phrase is The new value is ”[_1]”., then any value will still make sense: The new value is ””.
     • This also applies to values that might contain whitespace, etc.
  • The only exception is when the phrase introduces obviously disconnected and external text—such as an error message: Could not open “[_1]” for writing: [_2]
• 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 an 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 should be the ellipses character ( … ), not a string of multiple periods ( ... ).
    • Please include a single space on either side of the ellipsis. The only exception to this rule is when the ellipsis ends a sentence; in that case, it does not require a trailing space.
    • Look up the proper usage if you are unsure of the way an ellipsis should be used in a given context.
• Always express acronyms using capital letters.
  • Correct — The [output,acronym,FBI,Federal Bureau of Investigation] would like to have a word with you.
  • Incorrect — The [output,acronym,Fbi,Federal Bureau of Investigation] would like to have a word with you.
• 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].
• If a phrase consists of 2 or more sentences, use a single space after a period ( .) or other sentence-ending punctuation.
• Think about reusability. Instead of making multiple permutations of the same string, use bracket notation to make it reusable.
  • For example: Start with these phrases: List 10 records., List 25 records., … List 1,000 records.
  • If we did: List [numf,_1] records. then:
    • We can reuse this infinitely, with any number, with only one phrase.
    • Number formatting is handled by the locale.
    • It will be impossible to make dupes-via-type (for example, a phrase with 1000 and a phrase with 1,000).
  • This particular phrase could be improved even further by use of quant() instead of numf(). (So it could render List 1 record. instead of List 1 records.)

Note: You can also learn about the consistent way to incorporate special, non-ASCII, characters:

• Using Special Characters.