Helix Swarm Guide (2019.3)

Localization & non_UTF8 character display

Swarm supports localization and the display of some non-UTF8 characters.

Tip

If you make a configuration change, Swarm will not use it until the Swarm config cache has been deleted. For instructions on deleting the config cache, see Swarm config cache file delete.

Localization

Swarm is fully localized; with an appropriate language pack installation, Swarm can support users in multiple languages.

A language pack consists of gettext-style default.po and default.mo files, placed in a folder named for the locale they represent, within the language folder in the Swarm root directory. In addition, language packs contain two JavaScript files to provide translation strings for the in-browser UI, locale.js and locale.jsgz, which both appear in the SWARM_ROOT/public/build/language folder.

The following example illustrates the directory layout of a language pack:

SWARM_ROOT/
language/
locale/
default.mo
default.po
public/
build/
language/
locale.js
locale.jsgz

You can configure certain localization behaviors with the translator configuration block in the SWARM_ROOT/data/config.php file. Here is an example:

<?php
// this block should be a peer of 'p4'
'translator' => array(
'detect_locale' => true,
'locale' => "",
'translation_file_patterns' => array(),
),

The detect_locale key determines whether Swarm attempts to detect the browser's locale. The default value is true. Set the value to false to disable browser locale detection.

The locale key is a string specifying the default locale for Swarm. Alternately, an array of 2 strings can be used to specify the default locale, and a fallback locale. For example:

<?php
// this block should be a peer of 'p4'
'translator' => array(
'locale' => array("en_GB", "en_US"),
),

The translation_file_patterns key allows you to customize Zend's translation infrastructure, which you might do if you are developing your own language pack. For details, see Zend\I18n.

Note

Swarm supports Zend version 3.2.0, features and functions in the Zend documentation that were introduced in later versions of Zend will not work with Swarm.

Non-UTF8 character display

Swarm supports the display of non-UTF8 characters in file content when all of the following are true:

  • The Helix Core server is Unicode enabled.
  • The character encoding is supported by Swarm.
  • The character encoding is listed in the translator array.

Multiple character encodings can be specified in the array, if Swarm fails to find a matching encoding in the array it will fall back to windows-1252. Unsupported and invalid character encodings in the array are ignored.

Tip

For information on character encodings supported by Swarm, see http://php.net/manual/en/mbstring.supported-encodings.php

Configure character encodings by adding the following block to the swarm_root/data/config.php file. For example:

<?php
    // this block should be a peer of 'p4'
    'translator' => array(
        'non_utf8_encodings' => array('sjis', 'euc-jp', 'windows-1252'),
    ),
Important

windows-1252 is the default character encoding, it must always be the last entry in the array.