Localization & UTF8 character display

Important

To ensure that all characters, including Unicode characters, are displayed and handled correctly by Swarm, configure your Helix Core Server in Unicode mode. For information on configuring your Helix Core Server in Unicode mode, see Setting up and managing Unicode installations in the Helix Core Server Administrator Guide.

Tip

If you make a configuration change, Swarm will not use it until the configuration cache has been reloaded, this forces Swarm to use the new configuration. You must be an admin or super user to reload the Swarm config cache. Navigate to the User id dropdown menu, select System Information, click the Cache Info tab, and click the Reload Configuration button.

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

Localization

Important

If you are using a web browser that uses the en-US locale, Helix Swarm will automatically redirect to en to get locale files.

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 the Laminas translation infrastructure, which you might do if you are developing your own language pack. For details, see Laminas\I18n.

Note

Swarm supports the Laminas component versions in the LICENSE.txt file, features and functions in the Laminas documentation that were introduced in later versions of Laminas will not work with Swarm. The LICENSE.txt file is in the readme folder of your Swarm installation.

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.

UTF8 conversion

If Swarm is connected to a non-unicode enabled Helix Core Server, Swarm converts special characters to UTF8 by default. For ANSI and ASCII files, this can result in some special characters being displayed in the diff view incorrectly or not at all. To stop Swarm converting special characters to UTF8 and to display special characters as unknown (�), disable UTF8 conversion by setting utf8_convert to false.

Disable UTF8 character conversion 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(
        'utf8_convert' => false,
    ),

By default, the value of this configurable is true.