glFusion Wiki

Site Tools


glfusion:language

Language System

glFusion is internationalized. Instead of containing language specific text messages, it tracks text in a special way so that it can be extracted and translated into other languages. Users will see a version of the text that has been converted into their own language. This allows glFusion to be used in many countries and does not force English as the primary language.

glFusion is also aware of 'Right to Left' (RTL) languages too, so there are no restrictions on translating glFusion to any language.

The site administrator will select the default site language. Users can also select their preferred language under the 'My Account' options. There is an admin configuration option available that will disable a user's ability to change the language.

Keep in mind that unless you provide a translation of user created content (such as stories), they will only be available in the language they were originally written in. The exception to this is if the site visitor chooses to use the Auto Translations widget (documented below).

Translating glFusion

The language files are well commented and easy to customize the text displayed for any of the core glFusion screens. Plugins are also expected to use a language file for their user screens. A language subdirectory with the distributed plugin is where the different language files are located. The matching language file for the plugin will be selected if available.

To translate glFusion or any plugins to a new language, start with the english.php or english_utf-8.php file as the base. For the main glFusion language file, you'll want to look at private/language/english_utf-8.php, for plugins, you'll want to look at private/plugins/<PLUGINNAME>/language/english_utf-8.php. You can get these files from the current release archive, or from the glFusion GitHub Project Page.

To discover language differences between release versions of glFusion, you can use the diff tool in the glFusion GitHub Project Page to compare a release version with a previous release version.

Please submit any translations to http://www.glfusion.org so they can be included in future releases. Additionally, you can also use the Translation forum to discuss questions or to collaborate with other users on translating glFusion.

Multilingual Sites

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.

Creating Content

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:

  • general_en
  • general_de

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.

Blocks

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

  • $_CONF['locale']
  • $_CONF['date']
  • $_CONF['daytime']
  • $_CONF['shortdate']
  • $_CONF['dateonly']
  • $_CONF['timeonly']
  • $_CONF['week_start']
  • $_CONF['hour_mode']
  • $_CONF['thousand_separator']
  • $_CONF['decimal_separator']

by adding the corresponding _de entry into public_html/siteconfig.php.

Switching Languages

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)

Auto Translations Widget

In addition to the multi-language capabilities built into the core of glFusion, we also leverage Google's translation services.

The function WIDGET_autotranslations in private/system/lib-widgets.php builds a list of flag image links that, when clicked, will automatically translate your glFusion site to one of several languages. This translated page is persistent for the browser session, so if you continue to navigate the translated site, each page you visit will continue to be translated, until you close the browser window.

We have created a Widget that will automatically translate a glFusion site into 35 languages. Learn more about it in the Widget documentation.

glfusion/language.txt · Last modified: 2016/12/02 09:57 (external edit)

Page Tools