\phpDocumentor\TranslatorTranslator

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',
);

Summary

Methods
Properties
Constants
__construct()
setLocale()
addTranslations()
addTranslationFolder()
translate()
No public properties found
TRANSLATION_FILE_TYPE
DEFAULT_LOCALE
DEFAULT_DOMAIN
DEFAULT_PATTERN
No protected methods found
No protected properties found
N/A
No private methods found
No private properties found
N/A

Constants

TRANSLATION_FILE_TYPE

TRANSLATION_FILE_TYPE

The 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.

DEFAULT_LOCALE

DEFAULT_LOCALE

DEFAULT_DOMAIN

DEFAULT_DOMAIN

DEFAULT_PATTERN

DEFAULT_PATTERN

Methods

__construct()

__construct() 

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

setLocale()

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

Sets the default locale to use when translating messages.

Parameters

string $locale

Returns

\phpDocumentor\Translator\Translator

addTranslations()

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

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

Parameters

string $filename

Name of the file to add.

string|null $locale

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).

string $textDomain

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

Returns

$this

addTranslationFolder()

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

Adds a folder with files containing translation sources.

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`

Parameters

string $folder

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

array<mixed,string> $domains

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

Returns

$this

translate()

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

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

Parameters

string $message

The message or code to translate.

string $textDomain

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

null $locale

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

Returns

string