GettextMessageSource

API reference › yii › i18n › GettextMessageSource

class	`yii\i18n\GettextMessageSource`
Extends	`MessageSource` » `yii\base\Component` » `yii\base\BaseObject`
Implements	`yii\base\Configurable`
Since	2.0
Source	`framework/i18n/GettextMessageSource.php`

GettextMessageSource represents a message source that is based on GNU Gettext.

Each GettextMessageSource instance represents the message translations for a single domain. And each message category represents a message context in Gettext. Translated messages are stored as either a MO or PO file, depending on the $useMoFile property value.

All translations are saved under the $basePath directory.

Translations in one language are kept as MO or PO files under an individual subdirectory whose name is the language ID. The file name is specified via $catalog property, which defaults to ‘messages’.

Properties

Property	Type	Description	Defined by
`$basePath`	`string`	Base directory of messages files Default: `'@app/messages'`.	`GettextMessageSource`
`$behaviors` read-only	`array<yii\base\Behavior<static>>`	List of behaviors attached to this component.	`yii\base\Component`
`$catalog`	`string`	Sub-directory of messages files Default: `'messages'`.	`GettextMessageSource`
`$forceTranslation`	`bool`	Whether to force message translation when the source and target languages are the same. Default: `false`.	`MessageSource`
`$sourceLanguage`	`string\|null`	The language that the original messages are in. Default: `null`.	`MessageSource`
`$useBigEndian`	`bool`	Whether to use big-endian when reading and writing an integer Default: `false`.	`GettextMessageSource`
`$useMoFile`	`bool`	Whether to use generated MO files Default: `true`.	`GettextMessageSource`

Methods

Method	Description	Defined by
`__construct()`	Constructor.	`yii\base\BaseObject`
`__call()`	Calls the named method which is not a class method.	`yii\base\Component`
`__clone()`	This method is called after the object is created by cloning an existing one.	`yii\base\Component`
`__get()`	Returns the value of a component property.	`yii\base\Component`
`__isset()`	Checks if a property is set, i.e. defined and not null.	`yii\base\Component`
`__set()`	Sets the value of a component property.	`yii\base\Component`
`__unset()`	Sets a component property to be null.	`yii\base\Component`
`attachBehavior()`	Attaches a behavior to this component.	`yii\base\Component`
`attachBehaviors()`	Attaches a list of behaviors to the component.	`yii\base\Component`
`behaviors()`	Returns a list of behaviors that this component should behave as.	`yii\base\Component`
`canGetProperty()`	Returns a value indicating whether a property can be read.	`yii\base\Component`
`canSetProperty()`	Returns a value indicating whether a property can be set.	`yii\base\Component`
`className()` static	Returns the fully qualified name of this class.	`yii\base\BaseObject`
`detachBehavior()`	Detaches a behavior from the component.	`yii\base\Component`
`detachBehaviors()`	Detaches all behaviors from the component.	`yii\base\Component`
`ensureBehaviors()`	Makes sure that the behaviors declared in `behaviors()` are attached to this component.	`yii\base\Component`
`getBehavior()`	Returns the named behavior object.	`yii\base\Component`
`getBehaviors()`	Returns all behaviors attached to this component.	`yii\base\Component`
`hasEventHandlers()`	Returns a value indicating whether there is any handler attached to the named event.	`yii\base\Component`
`hasMethod()`	Returns a value indicating whether a method is defined.	`yii\base\Component`
`hasProperty()`	Returns a value indicating whether a property is defined for this component.	`yii\base\Component`
`init()`	Initializes this component.	`MessageSource`
`off()`	Detaches an existing event handler from this component.	`yii\base\Component`
`on()`	Attaches an event handler to an event.	`yii\base\Component`
`translate()`	Translates a message to the specified language.	`MessageSource`
`trigger()`	Triggers an event.	`yii\base\Component`
`getMessageFilePath()` protected	Returns message file path for the specified language and category.	`GettextMessageSource`
`loadFallbackMessages()` protected	The method is normally called by `loadMessages()` to load the fallback messages for the language.	`GettextMessageSource`
`loadMessages()` protected	Loads the message translation for the specified $language and $category.	`GettextMessageSource`
`loadMessagesFromFile()` protected	Loads the message translation for the specified language and category or returns null if file doesn’t exist.	`GettextMessageSource`
`translateMessage()` protected	Translates the specified message.	`MessageSource`

Events

Event	Type	Description	Defined by
`EVENT_MISSING_TRANSLATION`	`MissingTranslationEvent`	An event that is triggered when a message translation is not found. Event name: `'missingTranslation'`.	`MessageSource`

Constants

Constant	Value	Description	Defined by
`MO_FILE_EXT`	`'.mo'`		`GettextMessageSource`
`PO_FILE_EXT`	`'.po'`		`GettextMessageSource`

Method details

getMessageFilePath()

protected function getMessageFilePath(string $language): string

Returns message file path for the specified language and category.

Parameters

Parameter	Type	Description
`$language`	`string`	The target language

Returns

string: Path to message file

loadFallbackMessages()

protected function loadFallbackMessages(string $category, string $fallbackLanguage, array $messages, string $originalMessageFile): array

The method is normally called by loadMessages() to load the fallback messages for the language.

Method tries to load the $category messages for the $fallbackLanguage and adds them to the $messages array.

Parameters

Parameter	Type	Description
`$category`	`string`	The message category
`$fallbackLanguage`	`string`	The target fallback language
`$messages`	`array`	The array of previously loaded translation messages. The keys are original messages, and the values are the translated messages.
`$originalMessageFile`	`string`	The path to the file with messages. Used to log an error message in case when no translations were found.

Returns

array: The loaded messages. The keys are original messages, and the values are the translated messages.

Since

2.0.7

loadMessages()

protected function loadMessages(string $category, string $language): array

Loads the message translation for the specified $language and $category.

If translation for specific locale code such as en-US isn’t found it tries more generic en. When both are present, the en-US messages will be merged over en. See loadFallbackMessages() for details. If the $language is less specific than $sourceLanguage, the method will try to load the messages for $sourceLanguage. For example: $sourceLanguage is en-GB, $language is en. The method will load the messages for en and merge them over en-GB.

Parameters

Parameter	Type	Description
`$category`	`string`	The message category
`$language`	`string`	The target language

Returns

array: The loaded messages. The keys are original messages, and the values are translated messages.

See also

loadMessagesFromFile()

protected function loadMessagesFromFile(string $messageFile, string $category): array|null

Loads the message translation for the specified language and category or returns null if file doesn’t exist.

Parameters

Parameter	Type	Description
`$messageFile`	`string`	Path to message file
`$category`	`string`	The message category

Returns

array|null: Array of messages or null if file not found