Commenting language.php and some changes

Some commenting for Doxygen, simplified detect_language() a bit, added a new function get_language_name() that I will use soon or can be used in general to display localized language names from language codes.

include/language.php

@@ -1,22 +1,28 @@
-<?php /** @file */
+<?php
-
-
 /**
- * translation support
+ * @file
+ *
+ * @brief translation support
+ *
+ * This file contains functions to work with translations and other
+ * language related tasks.
  */
 
 
 /**
+ * @brief Get the browser's submitted preferred languages.
+ *
+ * This functions parses the HTTP_ACCEPT_LANGUAGE header sent by the browser and
+ * extracts the preferred languages and their priority.
  *
  * Get the language setting directly from system variables, bypassing get_config()
  * as database may not yet be configured.
  * 
  * If possible, we use the value from the browser.
  *
+ * @return array with ordered list of preferred languages from browser
  */
-
 function get_browser_language() {
-
 	$langs = array();
 
 	if (x($_SERVER,'HTTP_ACCEPT_LANGUAGE')) {
@@ -43,9 +49,18 @@ function get_browser_language() {
 	return $langs;
 }
 
-
+/**
+ * @brief Returns the best language for which also a translation exists.
+ *
+ * This function takes the results from get_browser_language() and compares it
+ * with the available translations and returns the best fitting language for 
+ * which there exists a translation.
+ *
+ * If there is no match fall back to config['system']['language']
+ *
+ * @return Language code in 2-letter ISO 639-1 (en).
+ */
 function get_best_language() {
-
 	$langs = get_browser_language();
 
 	if(isset($langs) && count($langs)) {
@@ -79,7 +94,6 @@ function push_lang($language) {
 	$a->strings = array();
 	load_translation_table($language);
 	$a->language = $language;
-
 }
 
 function pop_lang() {
@@ -109,7 +123,7 @@ function load_translation_table($lang, $install = false) {
 
 	if(! $install) {
 		$plugins = q("SELECT name FROM addon WHERE installed=1;");
-		if ($plugins!==false) {
+		if ($plugins !== false) {
 			foreach($plugins as $p) {
 				$name = $p['name'];
 				if(file_exists("addon/$name/lang/$lang/strings.php")) {
@@ -128,15 +142,18 @@ function load_translation_table($lang, $install = false) {
 
 }
 
-// translate string if translation exists
+/**
-
+ * @brief translate string if translation exists.
+ *
+ * @param s string that should get translated
+ * @return translated string if exsists, otherwise s
+ */
 function t($s) {
-
 	global $a;
 
 	if(x($a->strings,$s)) {
 		$t = $a->strings[$s];
-		return is_array($t)?$t[0]:$t;
+		return is_array($t) ? $t[0] : $t;
 	}
 	return $s;
 }
@@ -147,14 +164,14 @@ function tt($singular, $plural, $count){
 
 	if(x($a->strings,$singular)) {
 		$t = $a->strings[$singular];
-		$f = 'string_plural_select_' . str_replace('-','_',$a->language);
+		$f = 'string_plural_select_' . str_replace('-', '_', $a->language);
 		if(! function_exists($f))
 			$f = 'string_plural_select_default';
 		$k = $f($count);
-		return is_array($t)?$t[$k]:$t;
+		return is_array($t) ? $t[$k] : $t;
 	}
 	
-	if ($count!=1){
+	if ($count != 1){
 		return $plural;
 	} else {
 		return $singular;
@@ -168,84 +185,47 @@ function string_plural_select_default($n) {
 	return ($n != 1);
 }
 
-
+/**
-
+ * @brief Takes a string and tries to identify the language.
+ *
+ * It uses the pear library Text_LanguageDetect and it can identify 52 human languages.
+ * It returns the identified languges and a confidence score for each.
+ *
+ * Strings need to have a min length config['system']['language_detect_min_length']
+ * and you can influence the confidence that must be met before a result will get
+ * returned through config['system']['language_detect_min_confidence'].
+ *
+ * @see http://pear.php.net/package/Text_LanguageDetect
+ * @param s A string to examine
+ * @return Language code in 2-letter ISO 639-1 (en, de, fr) format
+ */
 function detect_language($s) {
-
-	$detected_languages = array(
-		'Albanian'   => 'sq',
-		'Arabic'     => 'ar',
-		'Azeri'      => 'az',
-		'Bengali'    => 'bn',
-		'Bulgarian'  => 'bg',
-		'Cebuano'    => '',
-		'Croatian'   => 'hr',
-		'Czech'      => 'cz',
-		'Danish'     => 'da',
-		'Dutch'      => 'nl',
-		'English'    => 'en',
-		'Estonian'   => 'et',
-		'Farsi'      => 'fa',
-		'Finnish'    => 'fi',
-		'French'     => 'fr',
-		'German'     => 'de',
-		'Hausa'      => 'ha',
-		'Hawaiian'   => '',
-		'Hindi'      => 'hi',
-		'Hungarian'  => 'hu',
-		'Icelandic'  => 'is',
-		'Indonesian' => 'id',
-		'Italian'    => 'it',
-		'Kazakh'     => 'kk',
-		'Kyrgyz'     => 'ky',
-		'Latin'      => 'la',
-		'Latvian'    => 'lv',
-		'Lithuanian' => 'lt',
-		'Macedonian' => 'mk',
-		'Mongolian'  => 'mn',
-		'Nepali'     => 'ne',
-		'Norwegian'  => 'no',
-		'Pashto'     => 'ps',
-		'Pidgin'     => '',
-		'Polish'     => 'pl',
-		'Portuguese' => 'pt',
-		'Romanian'   => 'ro',
-		'Russian'    => 'ru',
-		'Serbian'    => 'sr',
-		'Slovak'     => 'sk',
-		'Slovene'    => 'sl',
-		'Somali'     => 'so',
-		'Spanish'    => 'es',
-		'Swahili'    => 'sw',
-		'Swedish'    => 'sv',
-		'Tagalog'    => 'tl',
-		'Turkish'    => 'tr',
-		'Ukrainian'  => 'uk',
-		'Urdu'       => 'ur',
-		'Uzbek'      => 'uz',
-		'Vietnamese' => 'vi',
-		'Welsh'      => 'cy'
-	);
-
 	require_once('Text/LanguageDetect.php');
 
-	$min_length = get_config('system','language_detect_min_length');
+	$min_length = get_config('system', 'language_detect_min_length');
 	if($min_length === false)
 		$min_length = LANGUAGE_DETECT_MIN_LENGTH;
 
-	$min_confidence = get_config('system','language_detect_min_confidence');
+	$min_confidence = get_config('system', 'language_detect_min_confidence');
 	if($min_confidence === false)
 		$min_confidence = LANGUAGE_DETECT_MIN_CONFIDENCE;
 
-
+	// strip off bbcode
-	$naked_body = preg_replace('/\[(.+?)\]/','',$s);
+	$naked_body = preg_replace('/\[(.+?)\]/', '', $s);
-	if(mb_strlen($naked_body) < intval($min_length))
+	if(mb_strlen($naked_body) < intval($min_length)) {
+		logger('detect language: string length less than ' . intval($min_length), LOGGER_DATA);
 		return '';
+	}
 
 	$l = new Text_LanguageDetect;
-	$lng = $l->detectConfidence($naked_body);
+	try {
-
+		// return 2-letter ISO 639-1 (en) language code
-	logger('detect language: ' . print_r($lng,true) . $naked_body, LOGGER_DATA);
+		$l->setNameMode(2);
+		$lng = $l->detectConfidence($naked_body);
+		logger('detect language: ' . print_r($lng, true) . $naked_body, LOGGER_DATA);
+	} catch (Text_LanguageDetect_Exception $e) {
+		logger('detect language exception: ' . $e->getMessage(), LOGGER_DATA);
+	}
 
 	if((! $lng) || (! (x($lng,'language')))) {
 		return '';
@@ -256,6 +236,29 @@ function detect_language($s) {
 		return '';
 	}
 
-	return(($lng && (x($lng,'language'))) ? $detected_languages[ucfirst($lng['language'])] : '');
+	return($lng['language']);
-
 }
+
+/**
+ * @brief Returns the display name of a given language code.
+ *
+ * By default we use the localized language name. You can switch the result
+ * to any language with the optional 2nd parameter $l.
+ *
+ * $s and $l can be in any format that PHP's Locale understands. We will mostly
+ * use the 2-letter ISO 639-1 (en, de, fr) format.
+ *
+ * If nothing could be looked up it returns $s.
+ *
+ * @param $s Language code to look up
+ * @param $l (optional) In which language to return the name
+ * @return string with the language name, or $s if unrecognized
+ */
+function get_language_name($s, $l = null) {
+	if($l === null)
+		$l = $s;
+
+	logger('get_language_name: for ' . $s . ' in ' . $l . ' returns: ' . Locale::getDisplayLanguage($s, $l), LOGGER_DEBUG);
+	return Locale::getDisplayLanguage($s, $l);
+}
+