Implement cascade-style loading of language files

(as requested in issue bcit-ci#452)

system/core/Lang.php

@@ -96,29 +96,40 @@ public function load($langfile, $idiom = '', $return = FALSE, $add_suffix = TRUE
 			return;
 		}
 
-		// Determine where the language file is and load it
-		if ($alt_path !== '' && file_exists($alt_path.'language/'.$idiom.'/'.$langfile))
+		// Load the base file, so any others found can override it
+		$basepath = BASEPATH.'language/'.$idiom.'/'.$langfile;
+		if (($found = file_exists($basepath)) === TRUE)
 		{
-			include($alt_path.'language/'.$idiom.'/'.$langfile);
+			include($basepath);
+		}
+
+		// Do we have an alternative path to look in?
+		if ($alt_path !== '')
+		{
+			$alt_path .= 'language/'.$idiom.'/'.$langfile;
+			if (file_exists($alt_path))
+			{
+				include($alt_path);
+				$found = TRUE;
+			}
 		}
 		else
 		{
-			$found = FALSE;
-
 			foreach (get_instance()->load->get_package_paths(TRUE) as $package_path)
 			{
-				if (file_exists($package_path.'language/'.$idiom.'/'.$langfile))
+				$package_path .= 'language/'.$idiom.'/'.$langpath;
+				if ($basepath !== $package_path && file_exists($package_path))
 				{
-					include($package_path.'language/'.$idiom.'/'.$langfile);
+					include($package_path);
 					$found = TRUE;
 					break;
 				}
 			}
+		}
 
-			if ($found !== TRUE)
-			{
-				show_error('Unable to load the requested language file: language/'.$idiom.'/'.$langfile);
-			}
+		if ($found !== TRUE)
+		{
+			show_error('Unable to load the requested language file: language/'.$idiom.'/'.$langfile);
 		}
 
 		if ( ! isset($lang) OR ! is_array($lang))

user_guide_src/source/changelog.rst

@@ -254,9 +254,6 @@ Release Date: Not Released
    -  :doc:`Encryption Library <libraries/encryption>` changes include:
 	 -  Added support for hashing algorithms other than SHA1 and MD5.
 	 -  Removed previously deprecated ``sha1()`` method.
-   -  :doc:`Language Library <libraries/language>` changes include:
-	 -  Changed method ``load()`` to filter the language name with ``ctype_digit()``.
-	 -  Added an optional second parameter to method ``line()`` to disable error login for line keys that were not found.
    -  :doc:`Profiler Library <general/profiling>` now also displays database object names.
    -  :doc:`Migration Library <libraries/migration>` changes include:
 	 -  Added support for timestamp-based migrations (enabled by default).
@@ -309,6 +306,10 @@ Release Date: Not Released
    -  :doc:`URI Routing <general/routing>` changes include:
 	 -  Added possibility to route requests using callbacks.
 	 -  Added possibility to use dashes in the controller and method URI segments (translated to underscores).
+   -  :doc:`Language Library <libraries/language>` changes include:
+	 -  Changed method ``load()`` to filter the language name with ``ctype_digit()``.
+	 -  Added an optional second parameter to method ``line()`` to disable error login for line keys that were not found.
+	 -  Language files are now loaded in a cascading style with the one in **system/** always loaded and overriden afterwards, if another one is found.
 
 Bug fixes for 3.0
 ------------------

user_guide_src/source/libraries/language.rst

@@ -10,27 +10,26 @@ containing sets of language files. You can create your own language
 files as needed in order to display error and other messages in other
 languages.
 
-Language files are typically stored in your system/language directory.
-Alternately you can create a folder called language inside your
-application folder and store them there. CodeIgniter will look first in
-your application/language directory. If the directory does not exist or
-the specified language is not located there CI will instead look in your
-global system/language folder.
+Language files are typically stored in your **system/language/** directory.
+Alternately you can create a directory called language inside your
+application folder and store them there. CodeIgniter will always load the
+one in **system/language/** first and will then look for an override in
+your **application/language/** directory.
 
 .. note:: Each language should be stored in its own folder. For example,
 	the English files are located at: system/language/english
 
 Creating Language Files
 =======================
 
-Language files must be named with _lang.php as the file extension. For
+Language files must be named with **_lang.php** as the file extension. For
 example, let's say you want to create a file containing error messages.
 You might name it: error_lang.php
 
 Within the file you will assign each line of text to an array called
-$lang with this prototype::
+``$lang`` with this prototype::
 
-	$lang['language_key'] = "The actual message to be shown";
+	$lang['language_key'] = 'The actual message to be shown';
 
 .. note:: It's a good practice to use a common prefix for all messages
 	in a given file to avoid collisions with similarly named items in other
@@ -39,9 +38,9 @@ $lang with this prototype::
 
 ::
 
-	$lang['error_email_missing'] = "You must submit an email address";
-	$lang['error_url_missing'] = "You must submit a URL";
-	$lang['error_username_missing'] = "You must submit a username";
+	$lang['error_email_missing'] = 'You must submit an email address';
+	$lang['error_url_missing'] = 'You must submit a URL';
+	$lang['error_username_missing'] = 'You must submit a username';
 
 Loading A Language File
 =======================
@@ -54,7 +53,7 @@ first. Loading a language file is done with the following code::
 Where filename is the name of the file you wish to load (without the
 file extension), and language is the language set containing it (ie,
 english). If the second parameter is missing, the default language set
-in your *application/config/config.php* file will be used.
+in your **application/config/config.php** file will be used.
 
 .. note:: The *language* parameter can only consist of letters.
 
@@ -80,17 +79,14 @@ Using language lines as form labels
 -----------------------------------
 
 This feature has been deprecated from the language library and moved to
-the lang() function of the :doc:`Language
-helper <../helpers/language_helper>`.
+the :php:func:`lang()` function of the :doc:`Language Helper
+<../helpers/language_helper>`.
 
 Auto-loading Languages
 ======================
 
 If you find that you need a particular language globally throughout your
-application, you can tell CodeIgniter to
-:doc:`auto-load <../general/autoloader>` it during system
-initialization. This is done by opening the
-application/config/autoload.php file and adding the language(s) to the
-autoload array.
-
-
+application, you can tell CodeIgniter to :doc:`auto-load
+<../general/autoloader>` it during system initialization. This is done
+by opening the **application/config/autoload.php** file and adding the
+language(s) to the autoload array.