Issue #306 - The internationalization library: Creation of two functions api_is_western_name_order() and api_get_person_name() for maintaining the conventions for full person name constructed from the first name and the last name. The functions are documented and stable, developers may freely use them.

main/inc/lib/internationalization.lib.php

@@ -296,6 +296,65 @@ function api_get_months_long($language = null) {
 }
 
 
+/**
+ * ----------------------------------------------------------------------------
+ * Name order conventions
+ * ----------------------------------------------------------------------------
+ */
+
+/**
+ * Answers in what order names of a person to be shown or sorted, depending on a given language.
+ * @param string $language (optional)	Language indentificator. If it is omited, the current interface language is assumed.
+ * @return bool							The result TRUE means that the order shold be first_name last_name, FALSE means last_name first_name.
+ * Note: You may use this function:
+ * 1. for determing the order of the fields or columns "First name" and "Last name" in forms and tables;
+ * 2. for constructing the ORDER clause of SQL queries, related to first name and last name;
+ * 3. for adjusting php-implemented sorting by names in tables and reports.
+ */
+function api_is_western_name_order($language = null) {
+	static $order = array();
+	if (empty($language)) {
+		$language = api_get_interface_language();
+	}
+	$language = api_refine_language_id($language);
+	if (!isset($order[$language])) {
+		$conventions = &_get_name_conventions();
+		$convention = $conventions[$language];
+		if (_api_is_valid_name_convention($convention)) {
+			$order[$language] = (strpos($convention, '%f') < strpos($convention, '%l'));
+		} else {
+			$order[$language] = true;
+		}
+	}
+	return $order[$language];
+}
+
+/**
+ * Builds a person (full) name depending on the convention for a given language.
+ * @param string $first_name			The first name of the preson.
+ * @param string $last_name				The last name of the person.
+ * @param string $language (optional)	Language indentificator. If it is omited, the current interface language is assumed.
+ * @return bool							The result is sort of full name of the person.
+ * Sample results:
+ * Peter Ustinoff - the western order
+ * Ustinoff Peter - the eastern order
+ * Ustinoff, Peter - the librarians' order
+ * Note: See the file dokeos/main/inc/lib/internationalization_database/name_order_conventions.php
+ * where you can revise the convention for your language.
+ */
+function api_get_person_name($first_name, $last_name, $language = null) {
+	if (empty($language)) {
+		$language = api_get_interface_language();
+	}
+	$language = api_refine_language_id($language);
+	$conventions = &_get_name_conventions();
+	$convention = $conventions[$language];
+	if (_api_is_valid_name_convention($convention)) {
+		return str_replace(array('%f', '%l'), array($first_name, $last_name), $convention);
+	}
+	return $first_name . ' ' . $last_name;
+}
+
 /**
  * ----------------------------------------------------------------------------
  * Functions for internal use behind this API.

main/inc/lib/internationalization_database/name_order_conventions.php

@@ -0,0 +1,65 @@
+<?php
+
+/**
+ * @link http://en.wikipedia.org/wiki/Personal_name#Naming_convention
+ * You maight need to correct the value for your language. The possible values are:
+ * first_name last_name			- Western order
+ * last_name first_name			- Eastern order
+ * last_name, first_name		- Western libraries order
+ * For licensing terms, see dokeos_license.txt.
+ */
+return array(
+	'arabic' => 'first_name last_name',
+	'asturian' => 'first_name last_name',
+	'bosnian' => 'first_name last_name',
+	'brazilian' => 'first_name last_name',
+	'bulgarian' => 'first_name last_name',
+	'catalan' => 'first_name last_name',
+	'croatian' => 'first_name last_name',
+	'czech' => 'first_name last_name',
+	'danish' => 'first_name last_name',
+	'dari' => 'first_name last_name',
+	'dutch' => 'first_name last_name',
+	'english' => 'first_name last_name',
+	'euskera' => 'first_name last_name',
+	'esperanto' => 'first_name last_name',
+	'finnish' => 'first_name last_name',
+	'french' => 'first_name last_name',
+	'friulian' => 'first_name last_name',
+	'galician' => 'first_name last_name',
+	'georgian' => 'first_name last_name',
+	'german' => 'first_name last_name',
+	'greek' => 'first_name last_name',
+	'hebrew' => 'first_name last_name',
+	'hungarian' => 'last_name first_name', // Eastern order
+	'indonesian' => 'first_name last_name',
+	'italian' => 'first_name last_name',
+	'japanese' => 'last_name first_name', // Eastern order
+	'korean' => 'last_name first_name', // Eastern order
+	'latvian' => 'first_name last_name',
+	'lithuanian' => 'first_name last_name',
+	'macedonian' => 'first_name last_name',
+	'malay' => 'last_name first_name', // Eastern order
+	'norwegian' => 'first_name last_name',
+	'occitan' => 'first_name last_name',
+	'pashto' => 'first_name last_name',
+	'persian' => 'first_name last_name',
+	'polish' => 'first_name last_name',
+	'portuguese' => 'first_name last_name',
+	'quechua_cusco' => 'first_name last_name',
+	'romanian' => 'first_name last_name',
+	'russian' => 'first_name last_name',
+	'serbian' => 'first_name last_name',
+	'simpl_chinese' => 'last_name first_name', // Eastern order
+	'slovak' => 'first_name last_name',
+	'slovenian' => 'first_name last_name',
+	'spanish' => 'first_name last_name',
+	'swahili' => 'first_name last_name',
+	'swedish' => 'first_name last_name',
+	'thai' => 'first_name last_name',
+	'trad_chinese' => 'last_name first_name', // Eastern order
+	'turkce' => 'first_name last_name',
+	'ukrainian' => 'first_name last_name',
+	'vietnamese' => 'last_name first_name', // Eastern order
+	'yoruba' => 'first_name last_name'
+);

main/inc/lib/internationalization_database/non_utf8_encodings.php

@@ -59,5 +59,5 @@ return array(
 	'turkce' => array('WINDOWS-1254', 'ISO-8859-9'),
 	'ukrainian' => array('KOI8-U'),
 	'vietnamese' => array('WINDOWS-1258', 'VISCII', 'TCVN'),
-	'yoruba' => array('ISO-8859-15', 'WINDOWS-1252', 'ISO-8859-1'),
+	'yoruba' => array('ISO-8859-15', 'WINDOWS-1252', 'ISO-8859-1')
 );

main/inc/lib/internationalization_internal.lib.php

@@ -30,7 +30,7 @@
  * 4. At the end the string is purified from HTML entities.
  * @param string $string	This is the retrieved human language string.
  * @param string $language	A language identiticator.
- * @return string			Returns the human language string, checked for proper encodeing and purified.
+ * @return string			Returns the human language string, checked for proper encoding and purified.
  */
 function & _get_lang_purify(& $string, & $language) {
 	$system_encoding = api_get_system_encoding();
@@ -56,7 +56,7 @@ function & _get_lang_purify(& $string, & $language) {
 /**
  * Returns an array of translated week days and months, short and normal names.
  * @param string $language (optional)	Language indentificator. If it is omited, the current interface language is assumed.
- * @return string						Returns a multidimensional array with translated week days and months.
+ * @return array						Returns a multidimensional array with translated week days and months.
  */
 function &_api_get_day_month_names($language = null) {
 	static $date_parts = array();
@@ -77,3 +77,46 @@ function &_api_get_day_month_names($language = null) {
 	}
 	return $date_parts[$language];
 }
+
+
+/**
+ * ----------------------------------------------------------------------------
+ * Appendix to "Name order conventions"
+ * ----------------------------------------------------------------------------
+ */
+
+/**
+ * Returns an array of conventions (patterns) of writting personal names for all "known" languages.
+ * @return array	Returns the array in the following form: attay('language1 => 'pattern1', ...).
+ * @link http://en.wikipedia.org/wiki/Personal_name#Naming_convention
+ */
+function &_get_name_conventions() {
+	static $conventions;
+	if (!isset($conventions)) {
+		$file = dirname(__FILE__) . '/internationalization_database/name_order_conventions.php';
+		if (file_exists($file)) {
+			$conventions = include ($file);
+		} else {
+			$conventions = array('english' => 'first_name last_name');
+		}
+		$search = array('first_name', 'last_name');
+		$replacement = array('%f', '%l');
+		foreach ($conventions as $key => &$value) {
+			$value = str_ireplace($search, $replacement, $value);
+		}
+	}
+	return $conventions;
+}
+
+/**
+ * Checks whether the input namin convention (a pattern) is valid or not.
+ * @param string $convention	The input convention to be verified. 
+ * @return bool					Returns TRUE if the pattern is valid, FALSE othewise.
+ */
+function _api_is_valid_name_convention($convention) {
+	static $cache = array();
+	if (!isset($cache[$convention])) {
+		$cache[$convention] = !empty($convention) && strpos($convention, '%f') !== false && strpos($convention, '%l') !== false;
+	}
+	return $cache[$convention];
+}

main/inc/lib/multibyte_string_functions.lib.php

@@ -2507,9 +2507,12 @@ function api_is_encoding_supported($encoding) {
 
 
 /**
- * Returns the most-probably used non-UTF-8 encoding for the given language.
+ * Returns in an array the most-probably used non-UTF-8 encoding for the given language.
+ * The first (leading) value is actually used by the system at the moment.
  * @param string $language (optional)	The specified language, the default value is the user intrface language.
  * @return string						The correspondent encoding to the specified language.
+ * Note: See the file dokeos/main/inc/lib/internationalization_database/non_utf8_encodings.php
+ * if you wish to revise the leading non-UTF-8 encoding for your language.
  */
 function api_get_non_utf8_encoding($language = null) {
 	if (empty($language)) {