View source for Proposals/Better RTL Support

Mahara could improve its support for right-to-left languages. Here's how.

==Coding for multi-language compatibility==

===Use get_string()===

All text strings output to the page should be stored in a language pack and displaying using [https://wiki.mahara.org/index.php/Developer_Area/Language_strings#How_to_use_get_string.28.29_in_PHP get_string()] to allow for translations.

BAD:
  $string = 'You do not have permission to view the content of this folder.';

GOOD:
  $string = get_string('cannotviewfolder', 'artefact.file');

===Avoid concatenating strings===

If you need to join strings or variables together, use placeholders. Concatenating strings together should be avoided because the grammar of other languages may require them to be joined differently:

BAD:
  echo get_string('todayis', 'mahara') . $dayofweek;
  $string['todayis'] = 'Today is ';

GOOD:
  echo get_string('todayisx', 'mahara', $dayofweek);
  $string['todayisx'] = 'Today is %s';

===Use UTF-8 character encoding and mbstring functions===

Using htmlentities() without the 'encoding' argument will break in languages that rely on Unicode characters such as Cantonese (for PHP versions prior to 5.4).

BAD:
  $tag = htmlentities($tag);

GOOD:
  $tag = htmlentities($tag, ENT_QUOTES, 'UTF-8');

Functions ucfirst() and ucwords() shouldn't be used in output because the capitalisation rules are different in some languages.

If you really have to do it you can do following instead of ucwords():

GOOD:
  mb_convert_case($somestring, MB_CASE_TITLE, "UTF-8");

There doesn't appear to be an easy solution for ucfirst() but there are some ideas in the comments [http://php.net/manual/en/function.ucfirst.php here], or you could do something like:

<pre>
function mb_ucfirst($str, $encoding = 'UTF-8') {
    return mb_strtoupper(mb_substr($str, 0, 1, $encoding), $encoding) .
        mb_substr($str, 1, mb_strlen($str), $encoding);
}
function mb_lcfirst($str, $encoding = 'UTF-8') {
    return mb_strtolower(mb_substr($str, 0, 1, $encoding), $encoding) .
        mb_substr($str, 1, mb_strlen($str), $encoding);
}
</pre>

===Set the user language for emails===

Be aware that Mahara supports multiple languages at the same time where each user can pick their language. In some circumstances this means you need to specify the language you want to get a string in (by default this is the current user's language or the site's language if there isn't a current user).

For example, if sending emails via the cron this won't take into account the user's language preference:

BAD:
  $subject = get_string('emailsubject', 'mahara');
  email_user($userto, $userfrom, $subject, $messagetext, $messagehtml);

You need to do this instead:

GOOD:
  $userlang = $user->lang;
  $subject = get_string_from_language($userlang, 'emailsubject', 'mahara');
  email_user($userto, $userfrom, $subject, $messagetext, $messagehtml);

==Right-to-left language support==

In languages such as Hebrew and Arabic text flows from right-to-left instead of from left-to-right. In those languages all UI features need to be mirrored horizontally. To ensure compatibility follow these guidelines:

* Don't use inline styles. RTL languages need to override things like float:left to switch to float:right, so set alignment in the CSS then override it with a more specific selector.

* If an image is directional (for example a progress bar that fills up from the left), create one facing the opposite direction and refer to it from the stylesheet or via PHP.

===CSS===

Try and keep right-to-left styles close to the styles they are overriding:

BAD:
<pre>
.floating-block {
    float: right;
}
</pre>

GOOD:
<pre>
.block {
    float: right;
}
html[dir='rtl'] .block {
    float: left;
}
</pre>

===PHP===

You can find the current language direction in your PHP code using:

 $direction = get_string('thisdirection', 'langconfig');

===Javascript===
TODO