Actions

Difference between revisions of "Proposals/Better RTL Support"

From Mahara Wiki

< Proposals
Line 1: Line 1:
 
Mahara could improve its support for right-to-left languages. Here's how.
 
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 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);
  
 
TODO
 
TODO

Revision as of 20:21, 26 March 2015

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 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 here, or you could do something like:

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);
}

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);

TODO

Pagination function The numbers and arrows of the pagination function are displayed in an inverted manner, in which the numbers are shown as 321 instead of 123 and the arrows are also shown inverted. We managed to solve this issue, through developing an new function to handle RTL orientation for the pagination function.

Calendar The chosen calendar didn’t include the required translation resulting it halt, therefore it was not displayed at all. We translated the calendar now its functional.