Documentation/libraries/language.html

   1 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
   2 <head>
   3         <title>CarbonPHP Documentation</title>
   4         <style type="text/css">
   5                 * {
   6                         margin: 0;
   7                         padding: 0;
   8                 }
   9
  10                 html {
  11                         font-family: "Lucida Sans Unicode", "Lucida Grande";
  12                         font-size: 12px;
  13                 }
  14
  15                 body {
  16                         background: #fff;
  17                         color: #666;
  18                 }
  19
  20                 h1 {
  21                         font-size: 15px;
  22                         font-weight: bold;
  23                         margin: 0 0 5px 0;
  24                 }
  25
  26                 h2 {
  27                         font-size: 13px;
  28                         font-weight: bold;
  29                         margin: 5px 0 5px 0;
  30                 }
  31
  32                 ol, ul {
  33                         margin: 10px 0 10px 0;
  34                         list-style-position: inside;
  35                 }
  36
  37                 p {
  38                         margin: 5px 0 5px 0;
  39                 }
  40
  41                 .content {
  42                         border: 1px dotted #444;
  43                         margin: 10px;
  44                         padding: 10px;
  45                         text-align: justify;
  46                         width: 700px;
  47                 }
  48
  49                 .example {
  50                         border: 1px solid #ccc;
  51                         background: #eee;
  52                         margin: 10px;
  53                         padding: 10px;
  54                 }
  55         </style>
  56 </head>
  57
  58 <body>
  59         <div class="content">
  60                 <h1>Language Library</h1>
  61
  62                 <p>The language library provides an interface to retrieve language files and lines of text for the sole
  63                 purpose of internationalisation.</p>
  64
  65                 <p>In the CarbonPHP directory there is a directory called <b>languages</b> containing language files.  You
  66                 can create your own language files as needed in order to display errors and other messages in other
  67                 languages.</p>
  68
  69                 <p>Languages are typically stored in <b>carbon/languages/</b>.  You can alternately create a directory called
  70                 <b>languages</b> in your application directory.  CarbonPHP will look in the <b>application/languages/</b>
  71                 directory first.  <i>Note</i>: each language should be stored in its own directory.  For example <b>english</b>
  72                 language files will be stored in <b>carbon/languages/english/</b>.</p>
  73         </div>
  74
  75         <div class="content">
  76                 <h1>Creating Language Files</h1>
  77
  78                 <p>Language files must be named with <b>_lang.php</b> at the end.  For example if you wanted a language file to
  79                 contain error messages, you might name it <b>error_lang.php</b>.  Within the file you will assign each line
  80                 of text to an array called <b>$lang</b>.</p>
  81
  82                 <div class="example">
  83                         $lang['lang_key'] = 'This is a message in the language.';
  84                 </div>
  85
  86                 <p><i>Note</i>: it is good practice to prefix your array keys to avoid collisions with similarly named items
  87                 that could be in other files.  For example in the error language file you could do something like the
  88                 following.</p>
  89
  90                 <div class="example">
  91                         $lang['error_missing_url'] = 'The URL is missing';<br />
  92                         $lang['error_missing_input'] = 'The input is missing';<br />
  93                         $lang['error_missing_output'] = 'The output is missing';
  94                 </div>
  95         </div>
  96
  97         <div class="content">
  98                 <h1>Loading Language Files</h1>
  99
 100                 <p>In order to retrieve lines from a language file you must load the file.</p>
 101
 102                 <div class="example">
 103                         $this->lang->load('<b>filename</b>', '<b>language</b>');
 104                 </div>
 105
 106                 <p>Where <b>filename</b> is the name of the file you wish to load, without the file extension, and
 107                 <b>language</b> is the language set you want to load for example english.  If the second parameter is not
 108                 specified the default language from <b>application/config/config.php</b> will be used.</p>
 109         </div>
 110
 111         <div class="content">
 112                 <h1>Retrieving a Line of Text</h1>
 113
 114                 <p>Once you have loaded the language file you can retrieve any line of text from the file.</p>
 115
 116                 <div class="example">
 117                         $this->lang->line('<b>lang_key</b>');
 118                 </div>
 119
 120                 <p>Where <b>lang_key</b> is the array key of the line of text you wish to retrieve.  <i>Note</i>: this method
 121                 only returns the line, it does not echo it for you.</p>
 122         </div>
 123
 124         <div class="content">
 125                 <h1>Automatically Loading Language Files</h1>
 126
 127                 <p>You may find yourself loading a language file throughout your application, you can automatically load it
 128                 you can add it to the <b>application/config/autoload.php</b> configuration file.</p>
 129         </div>
 130
 131         <div class="content">
 132                 <h1>Language Class Methods</h1>
 133
 134                 <h2>public function __construct()</h2>
 135                 <p>This method initialises the class.</p>
 136
 137                 <h2>public function load($langfile = '', $idiom = '', $return = false)</h2>
 138                 <p>This method loads the language file <b>$langfile</b>.  If you specify <b>$idiom</b> it will load the file
 139                 from that language.  If <b>$return</b> is set to <b>true</b> it will return the <b>$lang</b> array.</p>
 140
 141                 <h2>public function line($line = '')</h2>
 142                 <p>This method returns the line specified at the array index <b>$line</b>.</p>
 143         </div>
 144 </body>
 145
 146 </html>