From d36f8528763ca8422677685dc502b66279b8b8fa Mon Sep 17 00:00:00 2001
From: James L Parry <jim_parry@bcit.ca>
Date: Mon, 24 Nov 2014 00:57:25 -0800
Subject: Enhance Language Class Writeup in User Guide (closes #674)

Added explanation for CodeIgniter's use of "idiom" versus standard abbreviations.
Provided additional examples as a guide.
Signed-off-by:James L Parry <jim_parry@bcit.ca>
---
 user_guide_src/source/libraries/language.rst | 90 +++++++++++++++++++++++++---
 1 file changed, 82 insertions(+), 8 deletions(-)

(limited to 'user_guide_src')

diff --git a/user_guide_src/source/libraries/language.rst b/user_guide_src/source/libraries/language.rst
index 6949c11c9..c3f9b6d5a 100644
--- a/user_guide_src/source/libraries/language.rst
+++ b/user_guide_src/source/libraries/language.rst
@@ -5,14 +5,24 @@ Language Class
 The Language Class provides functions to retrieve language files and
 lines of text for purposes of internationalization.
 
-In your CodeIgniter system folder you'll find one called language
-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 directory called language inside your
-application folder and store them there. CodeIgniter will always load the
+In your CodeIgniter **system** folder, you will find a **language**
+subfolder containing a set of language files for the **english** idiom. 
+The files in this folder (**system/language/english/**) define the regular messages,
+error messages, and other generally output terms or expressions, for the different parts
+of the CodeIgniter core framework.
+
+You can create or incorporate your own language
+files, as needed, in order to provide application-specific error and other messages,
+or to provide translations of the core messages into other languages.
+These translations or additional messages would go inside your application/language folder,
+with separate subfolders for each idiom (for instance french or german).
+
+The CodeIgniter framework comes with a set of language files for the "english" idiom.
+Additional approved translations for different idioms may be found in the 
+`CodeIgniter 3 Translations repositories <https://github.com/codeigniter3-translations>`_.
+Each repository deals with a single idiom.
+
+When CodeIgniter loads language files, it will load the
 one in **system/language/** first and will then look for an override in
 your **application/language/** directory.
 
@@ -26,6 +36,70 @@ your **application/language/** directory.
 
   <div class="custom-index container"></div>
 
+***************************
+Handling Multiple Languages
+***************************
+
+If you want to support multiple languages in your application, you would provide folders inside
+your **application/language/** directory for each of them, and you would specify the default 
+language in your **application/config/config.php**.
+
+The **application/language/english/** directory would contain any additional language files
+needed by your application, for instance for error messages.
+
+Each of the other idiom-specific directories would contain the core language files that you
+obtained from the translations repositories, or that you translated yourself, as well as
+any additional ones needed by your application.
+
+You would store the language you are currently using, for instance in a session variable.
+
+Sample Language Files
+=====================
+
+::
+
+    system/
+        language/
+            english/
+                ...
+                email_lang.php
+                form_validation_lang.php
+                ...
+
+    application/
+        language/
+            english/
+                error_messages_lang.php
+            french/
+                ...
+                email_lang.php
+                error_messages_lang.php
+                form_validation_lang.php
+                ...
+
+Example of switching languages
+==============================
+
+::
+
+        $idiom = $this->session->get_userdata('language');
+        $this->lang->load('error_messages',$idiom);
+        $oops = $this->lang->line('nessage_key');
+
+********************
+Internationalization
+********************
+
+The Language class in CodeIgniter is meant to provide an easy and lightweight way to support multiple
+languages in your application. It is not meant to be a full implementation of what is commonly called
+`internationalization and localization <http://en.wikipedia.org/wiki/Internationalization_and_localization>`_.
+
+We use the term "idiom" to refer to a language using its common name, 
+rather than using any of the international standards, such as "en", "en-US", or "en-CA-x-ca" for English
+and some of its variants.
+
+.. note:: There is nothing to prevent you from using those abbreviations in your application!
+
 ************************
 Using the Language Class
 ************************
-- 
cgit v1.2.3-24-g4f1b