Localisation

Traq ships with the English language as the default language. Alternative languages can be found in the languages forum.

The files linked there need to be downloaded and placed in the vendor/traq/locale directory.

Language file

A language file is a PHP class that contains the language info and translation strings:

class enAU extends \traq\libraries\Locale
{
    protected static $info = array(
        'name'   => "English (Australian)",
        'author' => "Your name here",

        // Language info
        'language'       => "English",
        'language_short' => "en",
        'locale'         => "AU"
    );

    protected function strings()
    {
        return array(
            'my_string' => "My String"
        );
    }
}

Translation Strings

Translation strings are stored in an key => value array.

Strings can be namespaced using dots, for example: errors.invalid_password.

Variables / "Placeholders"

It is inevitable that translation strings will need to include something dynamic, such as ticket counts. This is where variables or "placeholders" come into play.

Passing variables to the string is done by passing an array to the translate method like so:

$lang->translate('there_are_x_posts', array(1)); // => "There are 1 posts"

The translation string for the above example is There are {1} posts, which uses the n+1 format to include the variable. That is, the array index + 1. This functionality will change in the future.

Named variables

It is also possible to use a key => value array for named variables, like so:

// "Welcome {username}, you have {notifications} notifications"
$lang->translate(
    'welcome_x_you_have_x_notifications',
    array(
        'username'      => "Picard",
        'notifications' => 5
    )
);
Plurals

Lets say we have a translation string that needs to be pluralised, such as the ticket count. We can do this with the plural syntax.

The syntax for plurals looks like {plural:{variable_name}, {singular|plural}}, here's an example:

// "There {plural:{1}, {is {1} ticket|are {1} tickets}}"
$lang->translate("there_are_x_tickets", array(5));

The plural syntax is pretty simple once you understand it, the plural:{variable_name} part is what determines if the singular or plural form should be used.

The {singular|plural} part can be considered as an array of plural forms, languages with multiple plural forms can add more options simply by separating them with the pipe: |. See the calculate_enumeral class method.

Overriding functions

For languages that have multiple plural forms will need to override the caluclate_enumral class method.

This can be done simply be redeclaring it in the language class like so:

class enAU extends \traq\libraries\Locale
{
    public function calculate_numeral($numeral)
    {
        // Calculate and return numeral value to use, starting from 0.
    }
}

This can also be done with the translate, date, get_string, compile_string methods.

Activating the newly added language file

Activating a language can be done in one of two places,