This is a style guide for messages in the Sahana user interface.

• Sahana Translation Wiki Homepage
• Sahana Translation Glossary

Below are two main sections:

• Messages Style Guide for Developers
• Messages Style Guide for Translators [TO DO]

The former concerns the base-English UI messages that are embedded in the code within the standard code tree, and associated base-English strings in the default database. The latter concerns the translation of these base-English messages into other languages, using the Pootle system.

Here we make some general observations about the interactions of these two activities. To begin with, in an ideal world, we would have this situation:

1. The base-English messages can be relied on to be correct;
2. The translation system provides the base-English messages and sufficient context to make the best possible translation.

It will quickly become apparent to the translator that we are not in this ideal world. The base-English messages have spelling, capitalization, and grammar errors. This reduces confidence that other matters (punctuation, trailing spaces) are reliable. Part of the problem is that the feedback loop from the translators to the developers is awkward and largely manual. Another part is that during translation there is insufficient context about any particular string provided by the current system. To be more specific, let's briefly pretend we have the ideal tool, “Pootle-Plus”. This vaporware would do the following:

• For a particular string, show not just the files it occurs in, but have a separate (possibly tabbed) window into each instance of the source code at the right spot. Furthermore, the appropriate part of the web page (or dialog box) as rendered would also seen. This could be implemented by on-the-fly rendering or pre-rendered screenshots. (Alternatively, there could be a way to tag strings so that the translators knows their general type, e.g., menu, heading, tooltip, etc.).
• For a particular string, there would also be a suggestion box specifically for corrections/content-improvements to the base-English. All translators could see suggestions previously made. Furthermore, suggestions would automatically be posted to the developer bug list, and the bug tracking status displayed in Pootle-Plus. Once a string is corrected in the base, the matter is resolved and the suggestion automatically cleared.
• The translator could ask that another pre-existing translation be displayed as a copyable reference, in addition to the base-English.

OK, so we have none of that. As workarounds, to provide context, the Pootle translator, assigned to translate a particular .po file, can first look up the which modules are involved (there's a table), and review those modules, perhaps taking screenshots, and/or making notes about the planned translation. [HINT TO ANYONE LOOKING FOR WORK: A repository of screenshots of the latest build would be valuable here.] Screenshots help disambiguate how a string is used, so that, for example, the correct capitalization style can be chosen. Egregious problems found in the base English messages can be posted to the bug list.

The following rules and recommendations (shown as bullets) apply to the development of base-English UI messages that are embedded in the code tree and default database.

Many of these are general guidelines for web sites, a start on Sahana developing its own custom styles:

• Be consistent throughout site
• COMMENT: Capitalize all main words in page title headings, 2nd level heading.
• COMMENT: Style of lower-level headings…?.
• COMMENT: Capitalize all main words in menu items.
• COMMENT: Use sentences in tooltips and balloon help, and capitalize like any other sentence in paragraph body.

• Title text should be short
• Try to keep buttons legends short (e.g., under 20 characters if possible). Use tooltips to extend narration.
• COMMENT: Also applies to menu items.

• Do not use a colon after a text label in a group box or title bar….(COMMENT: or heading)
• For a field prompt (assumed left-justified) before a text entry field or list box:
  • it should be immediately followed by a colon without intervening space.
  • COMMENT: Source recommends a trailing space after colon. It may be preferable to avoid a trailing space if a better method is available to position the field horizontally.
  • COMMENT: Some alternative designs avoid trailing colons, or simply have no left prompts (because they use above-field/below-field headings, group boxes around single fields, or images as prompts).

• These items should NOT end in a period (unless the last word is an abbreviation).
  • Main heading text.
  • Any level of heading on its own line.
  • Breadcrumb.
  • Menu items.
  • Group box label.
• These items SHOULD end in a period:
  • All sentences in body paragraph, including last.
  • All sentences in tooltips, including last (controversial).
  • Ditto, help balloon.
• Treatment of bullet points… to be decided.

• There should be 1 space between sentences (because 2 takes too much work with non-breaking spaces).
• There should be 1 space between a colon and following text (for the same reason).
• A leading space before a string and/or a trailing space after a string should be used only if it serves a functional purpose. Subsequent translators will assume such spacing must be preserved.

• Try to keep paragraphs in the form of one string, instead of broken up into individual sentences or lines.
• If left-margin spacing is needed for a paragraph, use HTML or CSS, not leading spaces before individual lines.
• If paragraphs are centered, try to use HTML or CSS to do this, rather than leading spaces before individual lines.
• Paragraphs ordinarily don't have trailing spaces.

• Reference: GUI Standards

1. Every string which is visible in user interface should be within gettext.
2. Review whether developer uses HTML tags and/or HTML special characters(',“,<,etc.. ) within gettext.
3. Identify strings which are within gettext but can't be localized; then modify those strings to function correctly.
4. Review usage of database-stored localizations involving _lc().

• From l10n portion of SWAT doc
• See also: l10n

This is summarized from the 'Localization' section of PHP Coding Convention. Points going beyond or diverging from that source are noted as COMMENT.

• Try to localize all strings, using the gettext method invoked by _( ), for example:

<?php echo _("Organization Name")?>

• COMMENT: Use _( ) in preference to _t( ).
• Use double quotes to enclose strings.
• COMMENT: The reason for this recommendation is not clear, and it seems to conflict with another PHP Coding Convention recommendation (see 'Quoting String') to prefer enclosing single quotes over double unless a variable is involved.

We'll have to decide what is best, and make the example code consistent.

• If there any double quotes within a string (i.e., that will show in the UI), either
  • escape each one (\”)…

e.g, NOT:
_('Home page "http://sahana.lk" ')
instead:
_("Home page \"http://sahana.lk\" ")

• or split up the string and concatenate with the HTML double-quote character (&#34;)…

e.g, to generate:
To do this in the navigation bar click on "Multiple Incidents" followed by <a href="?mod=admin&act=ims_level1">"Manage Disaster"</a>
use:
_('To do this in the navigation bar click on ').'&#34;'._('Multiple Incidents').'&#34;'._(' followed by ').
'<a href="?mod=admin&act=ims_level1">'.'&#34;'._('Manage Disaster').'</a>';

• COMMENT: Avoid the second method, as it presents independent string fragments to the translators. Here's a third method that's better (though the example includes embedded HTML, violating another style rule):

_('To do this in the navigation bar click on '.'&#34;'.'Multiple Incidents'.'&#34;'.' followed by '.'<a href="?mod=admin&act=ims_level1">'.'&#34;'.'Manage Disaster');

• COMMENT: Prefer straight double quotes to left/right double quotes.
• Don't localize variables. Example of what NOT to do:

<?php echo _($org)?>

• Gettext should ideally contain only word phrases, not HTML markup.
• For instance, move enclosing HTML tags outside of gettext:

e.g, NOT:
_('<h2>Welcome to the Sahana FOSS Disaster Management System</h2>');
instead,
echo "<h2>"._('Welcome to the Sahana FOSS Disaster Management System')."</h2>";

• COMMENT: Generally, try to avoid word-level styling and non-ASCII characters, since these require problematic treatments, either:
  • embedded HTML tags; or
  • concatenated HTML special characters interspersed with gettext fragments.
• COMMENT: If there is a paragraph and one of its sentences is surrounded by HTML tags, split that out.
• COMMENT: If there is part within a sentence that MUST have HTML tags around it, it's better not to split it, but to live with it. This is an exception to the general rule.
• When writing a paragraph within gettext, make sure line breaks are not put in. Line breaks behave in a different manner in different editors. For instance, Eclipse puts in a line break when you press <enter> but Quanta doesn't, it just wraps it. As an example, Eclipse behaves as shown in the code below. This paragraph will then appear in a sahana.po file as separate lines, not in a paragraph. So Eclipse IDE users should write the paragraph in a single line. (Quanta would wrap this paragraph and it would appear in a sahana.po file as a paragraph as desired).

_("The SAHANA Disaster Victim Registry is a central online repository " .
"where information on all the disaster victims can be stored. Information like name, age" .
", contact number, id card number, religion, race, displaced location, current location and other ")

Like the above, this is summarized from the 'Localization' section of dev:php_coding_convention, with COMMENTs added.

The gettext framework doesn't support localization of strings stored in the database directly. Instead, the Sahana database has a 'lc_fields' table, with the table+field names whose content must be translated. COMMENT: The result goes into .po file #8.

Any database fields that need to be translated into other languages should be added to this table.

To display a value retrieved from the database in some other language, the developer should use the function _lc(). This function takes a single string as the parameter and will return the translated value of that string. If a translation is not available this will return the same value.

[ string ] _lc ( $string )

Given a record set $rs, this will display the non-translated key column and translated values of columns Priority and Description.

    foreach($rs as $r)
    {
    ?>
    <tr>
        <td><?php print  $r['priority_id'] ?></td>
        <td><?php print  _lc($r['priority']) ?></td>
        <td><?php print  _lc($r['description']) ?></td>
    </tr>
    <?php
    }

• [add your suggestions here, please enclose examples where appropriate]

The following rules and recommendations apply to the translation of UI messages:

• [add your suggestions here, please enclose examples where appropriate]