glFusion provides some support for providing content in multiple languages. If you plan to run a site where the content will be in several languages, you should use languages that support UTF-8. UTF-8 is a universal method to display characters. For example you could display a German Umlaut next to Japanese Characters.
How It Works
glFusion will use an item's ID to determine which language it is written in. For example, if you have a block with an ID of blockname, then blockname_en would be the English version and blockname_de would be the German version.
This is the way to identify the language of an object (article, topic, etc.) and it can be displayed (or not), based on the user's language preferences. It is also possible to switch between the various languages in which an object exists in the database.
Setting It Up
In your site's main Online Configuration, there is a section under Languages and Locale to enable multi-language support and to define the list of supported languages:
To enable multi-language support, the Language Files and Languages have to be defined. In the default configuration, they are not defined.
For Language Files you will map a 2 character identifier to the actual glFusion language file. For example:
en -> english_utf-8
de -> german_formal_utf-8
You can freely define these mappings, but it would make sense to set them in some relation to the language which they represent. From glFusion's point of view though, it doesn't matter whether the English language is represented by a identifier of 'en' or by 'foo'.
For Languages, you map the 2 character identifier to the common names for the language. For example:
en -> English
de -> Deutsch
Most of the time, you'll want to use the native names of the languages, e.g. “Deutsch” instead of “German”, but that's only a convention.
The settings for Language Files and Languages must match. This means if you define en and de, you must map en and de in the Languages section.
glFusion's multi-language support is available for Topcis / Stories, Blocks, and Menu Builder menus.
Topics / Stories
The topic ID is used to map topics to languages. For example, if we wanted to have a topic ID of general, then we would need to create:
Stories contained in general_en topic will display when English is the language and stories in general_de topic will display when German is the language.
If there is a story in general_en topic, but not a corresponding one in general_de topic, nothing will be displayed when German is selected.
To support mulit-language blocks, we must define at least 3 different block IDs:
blockname - This will be the main block and displayed if no language specific block is available. It should be enabled
blockname_en - This will override the blockname and be displayed instead when English is chosen. It should be disabled.
blockname_de - This will override the blockname and be displayed instead when German is chosen. It should be disabled.
Switching Locale Settings
Switching the language will often also require different formatting of the date, time, and other locale settings. For this, you can define alternative PHP date and time settings for each language in your public_html/siteconfig.php file.
For example, the default date formatting in glFusion's configuration is
Date Format: = '%A, %B %d %Y @ %I:%M %p %Z';
which, amoung other things, includes a time format using am/pm. If your site switches between, say, English and German, then your typical German visitor will expect the time to use a 24-hour format, for example.
Date Format = '%A, %d. %B %Y, %R Uhr';
If you're using the ISO abbreviation 'de' for German, then you could have the following in your site's configuration file (siteconfig.php):
$_CONF['date_de'] = '%A, %d. %B %Y, %R Uhr';
With this line, and the default Date Format setup in the online configuration, glFusion would use the 'date_de' formatting when displaying content in German, and the 'date' formatting for all the other languages.
Actually, for this to work properly, you will also have to set Locale in the online configuration and $_CONF['locale_de'] in siteconfig.php accordingly, since some of the date formatting (localized day and month names) requires the correct locale to be set:
Locale = 'en_GB';
$_CONF['locale_de'] = 'de_DE';
You can switch all of the following locale settings as described above
by adding the corresponding _de entry into public_html/siteconfig.php.
Registered users can always switch their preferred language by selecting another language in their preferences.
To make things more convenient (and also allow anonymous users to switch the language), you can put a PHP block on your site. glFusion provides a function phpblock_switch_language that will display a drop-down menu of all available languages (if you only have two languages defined, it will display a simple link to the other language instead).
This function can be called from the header.thtml template file of your theme, so that you can put it into your site's menu:
<?php print phpblock_switch_language(); ?>
Technically, switching the language will set a cookie (with the selected language) and also update a user's language preference, if they are registered with the site.
Detecting the Language
When a user comes to a multi-language enabled site, glFusion will check for the user's preference setting first (if it is a registered user), then for the language cookie, and if that couldn't be found, it tries to get the language from the browser's 'Accept-Language' header (which only works if you chose to use the ISO shortcuts, as explained above). If all else fails, content will be presented in the site's default language.
Developer Notes for Supporting Multiple Languages
Developers of plugins and other add-ons don't have to do much to support multiple languages. Mainly, the objects under your plugin's control will have to have an editable, non-numerical ID (like glFusion's stories have), so that the language shortcut can be appended to the ID.
If you have a list of objects under your plugin's control and only want to show the objects in the current language, you can use the COM_getLangSQL() function when building your SQL request. It will provide the part of an SQL request to only return the objects in the current language (see the function's description in lib-common.php for details).
COM_getLangSQL() will return an empty string when multi-language support is disabled, so you don't need to check for that yourself.
Most of the time, that should be all that you need to know about supporting multiple languages in a plugin. In some scenarios, the following functions may also come in handy:
COM_getLanguageId returns the shortcut of the current user's language
COM_getLanguage returns the full name of the current user's language, i.e. the name of the glFusion language file (without the .php extension)