Translator

Extends \Zend\I18n\Translator\Translator

Translator proxy for phpDocumentor.

This class encapsulates (or actually extends) a Translator object that can be used to translate messages from the fallback language to another.

This encapsulation serves two purposes;

  1. To make a migration to another translator easier if necessary
  2. To fix a bug in Zend\I18n\Translator\Translator where the cache is not cleared when new messages are added.

Due to issue 2 this class extends the Zend Translator and does not use composition to proxy calls to the translator; as such it is not recommended to use any public function not defined in this proxy as it may be removed.

Before invoking the \phpDocumentor\Translator\self::translate() method the user must first load a series of translation messages in the desired locale; this can be done by invoking the \phpDocumentor\Translator\self::addTranslationFile() or \phpDocumentor\Translator\self::addTranslationFolder() methods. These try to include a file containing a plain PHP Array and merge that with the translation table of this translator.

An example of a translation file can be:

return array(
    'KEY' => 'translated message',
);
package

Default

Methods

Pre-set the translator with the default locale as fallback.

__construct() 

Adds a folder with files containing translation sources.

addTranslationFolder(string $folder, array<mixed,string> $domains = array()) : $this
api

This method scans the provided folder for any file matching the following format:

`[domain].[locale].php`

If the domain matches the \self::DEFAULT_DOMAIN then that part is omitted and the filename should match:

`[locale].php`
link

for a list of ISO-639-1 locale codes as used by this method.

Arguments

$folder

string

Name of the folder, it is recommended to use an absolute path.

$domains

array<mixed,string>

One or more domains to load, when none is provided only the default is added.

Response

$this

Adds a translation file for a specific locale, or the default locale when none is provided.

addTranslations(string $filename, string|null $locale = self::DEFAULT_LOCALE, string $textDomain = self::DEFAULT_DOMAIN) : $this
api

Arguments

$filename

string

Name of the file to add.

$locale

string|null

The locale to assign to, matches {@link http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes ISO-639-1} and defaults to en (English).

$textDomain

string

Translations may be divided into separate files / domains; this represents in which domain the translation should be.

Response

$this

Sets the default locale to use when translating messages.

setLocale(string $locale) : \phpDocumentor\Translator\Translator
api

Arguments

$locale

string

Response

\phpDocumentor\Translator\Translator

Attempts to translate the given message or code into the provided locale.

translate(string $message, string $textDomain = self::DEFAULT_DOMAIN, null $locale = null) : string

Arguments

$message

string

The message or code to translate.

$textDomain

string

A message may be located in a domain, here you can provide in which.

$locale

null

The locale to translate to or the default if not set.

Response

string

Constants

The translation file type.

TRANSLATION_FILE_TYPE

This type is hardcoded into a constant to simplify the signature of the addTranslationFile and addTranslationFilePattern methods. This will simplify the migration to another component in the future as an incompatibility between two libraries may emerge due to differing types or typenames.

This translator class may be used by plugin developers to have translating elements in their plugins; as such the signatures here are considered to be stable / api.

var

DEFAULT_LOCALE

DEFAULT_LOCALE
var

Represents the default locale for phpDocumentor

DEFAULT_DOMAIN

DEFAULT_DOMAIN
var

Translation strings may be divided into 'domains', this is the default domain

DEFAULT_PATTERN

DEFAULT_PATTERN
var

the default name of files loaded by {@see self::addTranslationFolder()}