Documentation: LANG-system
From UniLang Wiki
The LANG-System is responsible for the ability to have all of our pages in multiple languages.
The variable $lang stores the user's language preference and reads it again from a cookie. The variable $l is used to override it and is always passed in the URL (this method guarantees language selection works without cookies). This all happens already as early as in /globalsettings.php
Contents |
LANG File Format
The translations of pages are stored in so-called LANG format in /translations/ , this is a plaintext utf-8 format and files are named PAGE.LANGUAGECODE.lang (example: index.en.lang). Pages don't correspond one on one with php-pages, a php-page can use multiple lang-files and a lang-file can be used in multiple php-pages. The lang format is structured as followed:
>id<version text >id<version text may span multiple rows and have newlines without any visible effect on the end-result (etc...)
The greater-than sign specifies an *id*, this is a short name by which this text/string is known. This all is **optionally** followed by a less-than sign and a *version number*, this is to distinguish an upgrade of the text from earlier versions. The version number, together with the less-than sign can be omitted, in which case it's interpreted as version number zero by the system. Mind that *id* is unique and can only occur once in the LANG-file (even if the version numbers are different).
Here an exerpt of an actual LANG-file, index.en.lang:
>langselect Select language >otherlang<0 View this site in another language >intro<2 The main purpose of the UniLang Community is to provide an online site where people interested in languages can unite, openly discuss, and find resources related to language(s), linguistics and translation.
Loading LANG files from PHP scripts
LANG-files are loaded into an array by /styles/loadlanguage.php , it is vital that this script is included in the PHP page, and since practically any other unilang page relies on it, it's included very early on, even before the header.
Loading a page into an array will go like this:
require($styledir . "/loadlanguage.php");
$pagetext = loadlanguage("pagename",$lang);
The first argument is the page name, the second argument the language-code (generally lang). Note that this system has a fallback mechanism, if the specified page does not exist in the specified language, it will load the english version. And will in addition print in red text:
This page is not available in the language you requested, you will therefore be presented the English version:
Moreover, if the page does exist in the language, but several strings are missing, then these strings will be loaded from the english version and will be printed in a lighter gray font (instead of the default) black (the HTML code to do this will be added to the english string automatically). This will also happen if the version number of the english string is higher than the version of the requested language's string (Cause this means a translation is not up to date).
The returned variable, in our example $pagetext, is an array, where the keys correspond with the *id*s of the loaded LANG-page. Suppose we load the file index.en.lang from a previous example of ours, then $pagetext['otherlang'] would return the text **"View this site in another language"**
The returned array also contains some other data:
- $pagetext['_page'] will return the name of the page (e.g: index)
- $pagetext['_lang'] will return the language code of the page (e.g: en)
- $pagetext['_name'] will return both: (e.g index.en)
- $pagetext['version'][$id] will return the version number for a given id.
Printing the strings from a LANG file
Printing the strings is already possible with a command like: echo $pagetext[$id];, but this method is archaic and as of September 2005 there is a new function which *should* be used:
printtext($pagetext, $id);
This functino (also defined in /styles/loadlanguage.php) is important since it helps the system keep track of what is being printed and it resolves variables, which will be discussed in the next section:
Variables
Since September 2005, LANG files can contain variables, using the syntax %variable%. Variables are defined in $langvars in /styles/loadlanguage.php, but may also be added at run time as we will see later on.
A short list of few of variables you can use (this list is not complete, check the source of loadlanguage.php for a complete list):
- %nick% - Will resolve to the nick-name of the logged-in user
- %unilangid% - Will resolve to the id-number of the logged-in user (or zero otherwise)
- %date% - Will resolve to the date in YYYY-MM-DD format
- %time% - Will resolve to the time on the server
- %baseurl% - Will resolve to the base url (e.g http://www.unilang.org)
- %mainurl% - Will resolve to the main url (e.g http://www.unilang.org/main)
New variables can be defined at run time by passing them to printtext in an optional third argument, can be set to empty or false if you don't want to add new variables.
$vars['%myvar%'] = '<b>Blah!</b>';
$vars['%mytime%'] = date('H:i:s');
printtext($pagetext, $id,$vars);
DoubleLang References
Now there's another special type of variable, a so-called doublelang reference. This allows you to use another lang string from with a lang string (both have to be from the same file). This is done by mentioning the *ID* between pipes (no percent signs). An example of a fictious lang file which using this functionality:
>text1 Hello >text2 When I enter a room I always say |text1| !
printtext($pagetext, 'text2'); would thus print: "When I enter a room I always say Hello !" .
- *Note 1:* Variables are resolved before doublelang references, so you can put a doublelang reference in a variable.
- *Note 2:* you can even use this recursively, variables, even doublelang references from the doublelang reference will be resolved as normal...
Printtext
There are two more optional arguments which can be passed to printtext, both are an integer of either 0 or 1. The fourth optional argument, if set to 1, states that printtext should refrain from actually printing the string and should merely return the text (it always returns the text btw). The fifth optional argument, if set to 1, states that HTML tags should be stripped from the text.
Debugging
Pass "langdebug=1" to any PHP script that uses the LANG-system and the footer will display extensive debug information, including a list of lang-pages loaded, a list of all *id*s printed, and a list of *id*s that failed to print (most likely because of a typo in the *id*)
