diff --git a/core/Core.php b/core/Core.php
index a59e4fc9b..d85ec20e7 100755
--- a/core/Core.php
+++ b/core/Core.php
@@ -85,13 +85,24 @@ function stripslashes_recursively(&$array) {
 
 /**
  * This is the main translator function. Returns the string defined by $class and $entity according to the currently set locale
+ *
+ * @param string $class Class where the entity was defined. It acts as a namespace.
+ * @param string $entity Entity that identifies the string inside the namespace.
+ * @param string $string The original string itself. In a usual call this is a mandatory parameter, but if you are reusing a string which
+ *				 has already been "declared" (using another call to this function, with the same class and entity), you can omit it.
+ * @param string $priority Optional parameter to set a translation priority. If a string is widely used, should have a high priority (PR_HIGH),
+ * 				    in this way translators will be able to prioritise this strings. If a string is rarely shown, you should use PR_LOW.
+ *				    You can use PR_MEDIUM as well. Leaving this field blank will be interpretated as a "normal" priority (less than PR_MEDIUM).
+ * @param string $context If the string can be difficult to translate by any reason, you can help translators with some more info using this param
+ *
+ * @return string The translated string, according to the currently set locale {@link i18n::setLocale()}
  */
-function _($class, $entity, $string="", $priority=100, $context="") {
+function _($class, $entity, $string="", $priority=40, $context="") {
 	global $lang;
 	$locale = i18n::getLocale();
 	$class = ereg_replace('.*([/\\]+)',"",$class);
 	if (substr($class,-4) == '.php') $class = substr($class,0,-4);
-	if (!$lang[$locale][$class]) i18n::includeByClass($class);
+	if (isset(!$lang[$locale][$class])) i18n::includeByClass($class);
 	$transEntity = $lang[i18n::getLocale()][$class][$entity];
 	return (is_array($transEntity) ? $transEntity[0] : $transEntity);
 }
diff --git a/core/i18n.php b/core/i18n.php
index 3adde5c5e..ab2e597c0 100755
--- a/core/i18n.php
+++ b/core/i18n.php
@@ -1,12 +1,30 @@
 <?php
 
+/**
+ * Silverstripe i18n API
+ *
+ * @author Bernat Foj Capell <bernat@silverstripe.com>
+ */
+
+/**
+ * Priorities definition. These constants are used in calls to _() as an optional argument
+ */
 define('PR_HIGH',100);
 define('PR_MEDIUM',50);
 define('PR_LOW',10);
 
 class i18n extends Controller {
-	static $currentlocale = 'en';
 	
+	/**
+	 * This static variable is used to store the current defined locale. Default value is 'en'
+	 */
+	static $currentlocale = 'en';
+
+	/**
+	 * This is the main method to build the master string tables with the original strings.
+	 * It will search for existent modules that use the i18n feature, parse the _() calls
+	 * and write the resultant files in the lang folder of each module.
+	 */	
 	static function textCollector() {
 	
 		if (!Permission::check("ADMIN")) die("You must be an admin to enable text collector mode");
@@ -29,6 +47,12 @@ class i18n extends Controller {
 	
 	}
 
+	/**
+	 * Searches for all the files in a given module
+	 *
+	 * @param string $baseDir Silverstripe's base directory
+	 * @param string $module Module's name
+	 */
 	private static function processModule($baseDir, $module) {	
 		if(is_dir("$baseDir/$module") && !in_array($module, array('sapphire','jsparty','assets')) && substr($module,0,1) != '.') {
 			i18n::getFilesRec("$baseDir/$module/code", $fileList);
@@ -60,6 +84,12 @@ class i18n extends Controller {
 		}
 	}
 
+	/**
+	 * Helper function that searches for potential files to be parsed
+	 * 
+	 * @param string $folder base directory to scan (will scan recursively)
+	 * @param array $fileList Array where potential files will be added to
+	 */
 	private static function getFilesRec($folder, &$fileList) {
 		$items = scandir($folder);
 		if($items) foreach($items as $item) {
@@ -71,7 +101,11 @@ class i18n extends Controller {
 	}
 	
 	/**
-	 * Look for calls to the underscore function and build our MST 
+	 * Look for calls to the underscore function in php files and build our MST 
+	 * 
+	 * @param string $index Classname used to namespace strings 
+	 * @param string $file Path to the file to be parsed
+	 * @return string Built Master String Table from this file
 	 */
 	private static function reportCallsCode($index, $file) {
 		static $callMap;
@@ -99,8 +133,12 @@ class i18n extends Controller {
 	}
 
 	/**
-	 * Look for calls to the underscore function and build our MST 
+	 * Look for calls to the underscore function in template files and build our MST 
 	 * Template version - no "class" argument
+	 * 
+	 * @param string $index Index used to namespace strings 
+	 * @param string $file Path to the file to be parsed
+	 * @return string Built Master String Table from this file
 	 */
 	private static function reportCallsTpl($index, $file) {
 		static $callMap;
@@ -126,18 +164,33 @@ class i18n extends Controller {
 		return $mst;
 	}
 
+	/**
+	 * Set the current locale
+	 * See http://unicode.org/cldr/data/diff/supplemental/languages_and_territories.html for a list of possible locales
+	 * 
+	 * @param string $locale Locale to be set 
+	 */
 	static function setLocale($locale) {
 		if ($locale) i18n::$currentlocale = $locale;
 	}
+
+	/**
+	 * Get the current locale
+	 * 
+	 * @return string Current locale in the system
+	 */
 	static function getLocale() {
 		return i18n::$currentlocale;
 	}
 	
 	/**
 	 * Includes all available language files for a certain defined locale
+	 * 
+	 * @param string $locale All resources from any module in locale $locale will be loaded
 	 */
 	static function includeByLocale($locale) {
-		$topLevel = scandir(Director::baseFolder());
+		if (file_exists($file = Director::getAbsFile("cms/lang/$locale.php"))) include_once($file);
+		$topLevel = array_diff(scandir(Director::baseFolder()),array('cms'));
 		foreach($topLevel as $module) {
 			if (file_exists($file = Director::getAbsFile("$module/lang/$locale.php"))) { 
 				include_once($file);
@@ -148,7 +201,9 @@ class i18n extends Controller {
 	/**
 	 * Given a class name (a "locale namespace"), will search for its module and, if available,
 	 * will load the resources for the currently defined locale.
-	 * If not available, the original english resource will be loaded instead (to avoid blanks)
+	 * If not available, the original English resource will be loaded instead (to avoid blanks)
+	 * 
+	 * @param string $class Resources for this class will be included, according to the set locale.
 	 */
 	static function includeByClass($class) {
 		if (substr($class,-3) == '.ss') {
@@ -160,7 +215,7 @@ class i18n extends Controller {
 			global $_CLASS_MANIFEST;
 			$path = $_CLASS_MANIFEST[$class];
 			ereg('.*/([^/]+)/code/',$path,$module);
-		}//die($class);
+		}
 		if (file_exists($file = Director::getAbsFile("{$module[1]}/lang/". i18n::getLocale() . '.php'))) {
 			include_once($file);
 		} else if (i18n::getLocale() != 'en') {