Skip to content

Latest commit

 

History

History
128 lines (102 loc) · 5.35 KB

i18n.md

File metadata and controls

128 lines (102 loc) · 5.35 KB
Raw

Internationalization

System Languages

At various parts of the system, there are several possibilities for the language selection of the "local" language:

  1. User (client or agent) preference
  2. Ticket thread (for system activity notes)
  3. System (for logs and administrative messages)

The system is flexible enough to support these different cases and provides a few wrapper functions to connect your string to the appropriate language. Bear in mind when writing new code that strings may need to be translated into more than one language. For instance, if a string is to be displayed as an error in a web page as well as appear in an email to the administrator, it may need to be translated differently for both.

Consider a Spanish-speaking user visiting a German-based help desk. After attempting to log in several times, they receive an error banner with a particular message. A message is also sent to the site administrator warning about possible brute force attack. These messages will need to consider different audiences when being localized. The site administrator should receive a warning email in German; whereas the user should see a Spanish error message with details about what to do next.

Creating localized strings

Creating localized strings in osTicket is similar to creating localized strings in any gettext-based project. osTicket has opted to use a pure-php version of gettext in order to avoid possible pitfalls surrounding usage of gettext with PHP including

  • MO file caching requiring HTTP server restart
  • gettext missing from the PHP installation
  • Requirement of locale pre-configuration on the server

Adding new strings

Use a few function calls to get your text localized:

  • __('string') localize the string to the current user preference
  • _N('string', 'strings', n) localize a string with plural alternatives to the current user locale preference.
  • _S('string') localize the string to the system primary language
  • _NS('string', 'strings', n) localize a string with plural alternatives to the system primary language.
  • _L('string', locale) localize a string to a named locale. This is useful in a ticket thread, for instance, which may have a language preference separate from both the user and the system primary language
  • _NL('string', 'strings', n, locale) localize a string with plural alternatives to a specific locale.
  • _P('context', 'string') localize a string which may have the same source text as another string but have a different context or usage. An example would be open used as a noun, adjective, and verb.
  • _NP('context', 'string', 'strings', n) localize a string with plural alternatives which may have different contexts in the source language.

In some cases, it is not possible to use a function to translate your string. For instance, if it is used a as a class constant or default value for a class variable. In such a case, a hint can be used to tell the POT scanner to translate the string for use elsewhere. As an example, one might set something like this up:

    class A {
        static $name = /* @trans */ 'Localized string';
    }

    print __(A::$name);

In this case the localized version of the class variable is translated when it is used — not when it is defined.

The * @trans * text in comment is significant. Both the asterisks and the term @trans are used to signify that the phrase should be made translatable. The comment must also be placed immedately before or after the string without any other PHP symbols in between (like the semi-colon).

Adding context to your strings

Your text may be ambiguous or unclear when it is viewed outside the context of the code in which it appears. The system allows adding of comments similar to the stock gettext tools. Any comments written directly beside (behind or in front of) a localized string will be captured with the string in the translation template. For instance

    print __('Localized' /* These comments are exported */);

All types of PHP comments are supported. They must be placed inside the parentheses of the localization call. If using single-line comments, use multiple lines if necessary to define the call so that your single-line comments can be used. For instance:

    print sprintf(__(
        // Tokens will be <a> of <b> <object(s)>
        '%1$d of %2$d %3$s'
        ),
        $a, $b,
        _N('object', 'objects', $b)
    );

Building POT file for translations

Use the command line to compile the POT file to standard out

php setup/cli/manage.php i18n make-pot > message.pot

Building language packs

In an effort for the php version of gettext to offer similar performance to the extension counterpart, a variant of the MO file is used which is a PHP serialized array written to a file. The original MO file functions basically like a text array. In stead of searching through the MO file for each string to be translated, the original and translated texts are placed into a hash array for quick access and the hash array is serialized for the language pack. At runtime, the hash array is recreated from the export and the strings are quickly accessed from the PHP hash array.

A MO file can be manually compiled using a command-line interface

php include/class.translation.php message.mo > message.mo.php