Browse Source

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.

Ivan Tcholakov 15 years ago
parent
commit
ccaf540550

+ 59 - 0
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.

+ 65 - 0
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'
+);

+ 1 - 1
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')
 );

+ 45 - 2
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];
+}

+ 4 - 1
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)) {