FDSE :: Help :: Dynamically changing the interface language

Home > Fluid Dynamics Search Engine > Help > 1165

Dynamically changing the interface language

FDSE is available in multiple languages. The FDSE code itself is language-independent; during each execution, it selects a language from one of the available packages and uses that language for printing text to the screen. This selected language is known as the interface language.

Thanks to this multi-language support, you can control which language is used via a single setting found in the web-based Admin Page. In addition, you can allow each visitor to select his interface language via an HTML form. You can also configure FDSE to auto-detect your visitor's language preferences from browser settings.

Follow these steps to customize the interface language:

Install FDSE version 2.0.0.0056 or newer. These instructions refer to some functionality introduced in the 0056 release.
Login to your Admin Page and select "User Interface" from the navigation menu.
On the User Interface page, scroll down to the section "Language and Locale Settings". There you can:
- Review which language packages are installed.
- Add new packages or update existing ones.
- Select the primary interface language using the radio button.
  This primary setting will control the language on all admin pages. It will control the language on the public search pages when your visitors have not otherwise selected a language.
Also on the User Interface page, in the group of settings at the top, is the setting "User Language Selection". Edit this setting to control whether visitors will be able to select a language via a form and/or whether their browser setting will be auto-detected.
If you allow your visitors to select the interface language via a form, you will need to create a form that they can fill out. The name of the form element must be "set:lang" and the value must be the name of the language folder within:
```
/search/searchdata/templates/
```
Historically FDSE has named language folders with lowercase English-type names, like "italian" and "dutch". All new translations are named using the two-letter ISO code, like "ar" and "tl".

Within FDSE templates, you can use a replacement variable named %lang_options%. This variable expands to a set of tags like <option value="english">English</option>. You can use this variable within your search form like so:
```
<p>Diplay search interface in <select name="set:lang">%lang_options%</select>.</p>
```
You can also directly set the "set:lang" variable within a URL.

Examples include:

Keyword:
Display search interface in .

http://www.xav.com/search.pl?set:lang=german (direct link to German interface)
No special settings need to be made when auto-detecting the visitor language via the browser settings. FDSE will look at the first two characters of the HTTP_ACCEPT_LANGUAGE environment variable and attempt to map them to an existing language package.

Once you've allowed for visitor selection of the interface language, you should thoroughly test your system. Here are some things to keep in mind:

MAJOR ISSUE with customized templates

A few FDSE templates are stored on a language-by-language basis, such as "tips.htm" and "searchform.htm". In general, when FDSE prints a template, it looks first in the language folder i.e. /search/searchdata/templates/english/ and then in successively higher-level folders. Templates that contain layout information without text are stored in the upper folder /search/searchdata/templates/ (for example, header.htm, footer.htm, style.inc). This way you only need to maintain one copy. On the other hand, the templates that contain text are stored in language specific subfolders, like:
```
/search/searchdata/templates/english/tips.htm
/search/searchdata/templates/german/tips.htm
/search/searchdata/templates/italian/tips.htm
/search/searchdata/templates/dutch/tips.htm
```
If you are using user-defined languages and you want to customize these templates, then you should customize each file in the same way. Failing to customize them all won't break the script but it will prevent your site layout from being consistent.
Error handling

FDSE decides which language to use early in its execution cycle, before it has printed headers to screen. At that stage, it cannot print debug messages if the user's browser language or form selection have problems. For example, a user might select "language: foobar" from a select list, but when FDSE tries to load the strings for that language, maybe it will get a permission denied error, or the strings.txt file will be from an older version. In a perfect world we would at least provide a warning message so the user knows that we tried, but that is not possible here.

FDSE is designed to go "full stop" on any errors when in admin mode, because the admin has the power and the competence to fix the problems. In user mode, however, FDSE just tries to do its best to continue the execution. Thus, if there are any errors in loading a custom language, FDSE will silently ignore the errors and use the system default instead.

If you have problems in which your custom languages don't seem to work, go to Admin Page => User Interface => Language and Locale Settings and try setting the custom language there. If there are any errors loading that language, then you should see them from within the admin area.
Cache management

FDSE maintains a cache file at:
```
/search/searchdata/valid_languages_cache.txt
```
This cache file contains a list of all languages that are installed. It uses this list to decide whether to accept a visitor's form-selected or browser-defined language. It also uses this list to create the %lang_options% replacement variable for use within templates.

The cache will be reset under the following conditions:
- whenever it is more than 24 hours old
- whenever the timestamp on the /templates/ folder has changed since the cache was built (the timestamp will be touched whenever new language subfolders are added, or existing ones taken away)
- whenever the "install" or "update" language package links are used at Admin Page => User Interface
- whenever the version of FDSE has been updated since the cache was built
Overriding the cache

In certain rare cases, you will need to manually reset the cache. To do this, simple connect via FTP and delete the file. A new one will be automatically created.

The only case the author can think of is if you have an existing language subfolder like /searchdata/templates/foobar/ which contains an outdated translation for an earlier version. If you manually update the strings.txt file within this subfolder to update it to the current version, then it will take 24 hours for the cache to detect that it is now valid.

In this case, you should just delete the file, and the script will run its language-discovery process again and immediately recognize "foobar" as a valid language.

To prevent the cache from operating at all, create a folder named "valid_languages_cache.txt" in your searchdata folder. FDSE will be unable to save any cache information because the file namespace is taken up by the folder. FDSE will then perform language discovery with each request.

History: the "set:lang" form element was instroduced in FDSE 2.0.0.0054. Browser detection and the various web-based settings to control it were introduced in version 2.0.0.0056.

Ian Dobson provided the code for this functionality. Thanks Ian!

    "Dynamically changing the interface language"
    http://www.xav.com/scripts/search/help/1165.html