Replaces gettext("message id") and _("message id") with the translated string.

Gettext is great for creating multi-lingual sites, but in some cases (e.g. for performance reasons) you may wish to replace the gettext calls with the translations of the strings; that's what this task is for. Note that this is similar to ReplaceTokens, but both the find and the replace aspect is more complicated -- hence this is a separate, stand-alone filter.

<

p> Example:

author | Hans Lellelid
version | $Id$
access | public
see | \global\BaseFilterReader
package | phing.filters
copyright | 2003 seasonfive. All rights reserved

### Methods

## Constructor used by Phing's introspection mechanism.

    __construct(\Reader $in)

Inherited

The original filter reader is only used for chaining purposes, never for filtering purposes (and indeed it would be useless for filtering purposes, as it has no real data to filter). ChainedReaderHelper uses this placeholder instance to create a chain of real filters.

inherited_from | \BaseFilterReader::__construct()
inherited_from | \BaseParamFilterReader::__construct()

### Parameters

#### $in

`\Reader`

## Creates a new TranslateGettext filter using the passed in Reader for instantiation.

    chain(\Reader $reader) : \TranslateGettext

### Parameters

#### $reader

`\Reader`

A Reader object providing the underlying stream. Must not be `null`.

### Returns

`\TranslateGettext`A new filter based on this configuration, but filtering the specified reader

## Close stream.

    close()

Inherited

inherited_from | \FilterReader::close()
inherited_from | \BaseFilterReader::close()
inherited_from | \BaseParamFilterReader::close()

### Exceptions

`\IOException` | if there is an error closing stream

## Returns whether the end of file has been reached with input stream.

    eof() : boolean

Inherited

inherited_from | \BaseFilterReader::eof()
inherited_from | \BaseParamFilterReader::eof()

### Returns

`boolean`

## Gets the root locale directory.

    getDir() : \PhingFile

### Returns

`\PhingFile`

## Get the current domain.

    getDomain() : string

### Returns

`string`

## Returns the initialized status.

    getInitialized() : boolean

Inherited

inherited_from | \BaseFilterReader::getInitialized()
inherited_from | \BaseParamFilterReader::getInitialized()

### Returns

`boolean`whether or not the filter is initialized

## Gets the locale to use for translation.

    getLocale() : string

### Returns

`string`

## getParameters()

    getParameters()

Inherited

inherited_from | \BaseParamFilterReader::getParameters()

## Returns the project this filter is part of.

    getProject() : object

Inherited

inherited_from | \BaseFilterReader::getProject()
inherited_from | \BaseParamFilterReader::getProject()

### Returns

`object`The project this filter is part of

## Returns the filename, url, etc.

    getResource() : string

Inherited

that is being read from. This is critical for, e.g., ExpatParser's ability to know the filename that is throwing an ExpatParserException, etc.

inherited_from | \FilterReader::getResource()
inherited_from | \BaseFilterReader::getResource()
inherited_from | \BaseParamFilterReader::getResource()

### Returns

`string`

## Convenience method to support logging in filters.

    log(string $msg, int $level)

Inherited

inherited_from | \BaseFilterReader::log()
inherited_from | \BaseParamFilterReader::log()

### Parameters

#### $msg

`string`

Message to log.

#### $level

`int`

Priority level.

## If supported, places a "marker" (like a bookmark) at current stream position.

    mark()

Inherited

A subsequent call to reset() will move stream position back to last marker (if supported).

inherited_from | \Reader::mark()
inherited_from | \FilterReader::mark()
inherited_from | \BaseFilterReader::mark()
inherited_from | \BaseParamFilterReader::mark()

## Whether marking is supported.

    markSupported() : boolean

Inherited

inherited_from | \Reader::markSupported()
inherited_from | \FilterReader::markSupported()
inherited_from | \BaseFilterReader::markSupported()
inherited_from | \BaseParamFilterReader::markSupported()

### Returns

`boolean`

## Returns the filtered stream.

    read(\off $len) : mixed

The original stream is first read in fully, and then translation is performed.

### Parameters

#### $len

`\off`

Offset at which to start storing characters.

### Exceptions

`\IOException` | - if the underlying stream throws an IOException during reading
`\BuildException` | - if the correct params are not supplied

### Returns

`mixed`the filtered stream, or -1 if the end of the resulting stream has been reached.

## Reads a line of text ending with '\n' (or until the end of the stream).

    readLine() : \the

Inherited

The returned String retains the '\n'.

inherited_from | \BaseFilterReader::readLine()
inherited_from | \BaseParamFilterReader::readLine()

### Exceptions

`\IOException` | if the underlying reader throws one during reading

### Returns

`\the`line read, or `null` if the end of the stream has already been reached

## Is stream ready for reading.

    ready() : boolean

Inherited

inherited_from | \Reader::ready()
inherited_from | \FilterReader::ready()
inherited_from | \BaseFilterReader::ready()
inherited_from | \BaseParamFilterReader::ready()

### Returns

`boolean`

## Reset the current position in stream to beginning or last mark (if supported).

    reset()

Inherited

inherited_from | \FilterReader::reset()
inherited_from | \BaseFilterReader::reset()
inherited_from | \BaseParamFilterReader::reset()

## Sets the root locale directory.

    setDir(\PhingFile $dir)

### Parameters

#### $dir

`\PhingFile`

## Set the text domain to use.

    setDomain(string $domain)

The text domain must correspond to the name of the compiled .mo files. E.g. "messages" ==> $dir/LC_MESSAGES/messages.mo "mydomain" ==> $dir/LC_MESSAGES/mydomain.mo

### Parameters

#### $domain

`string`

## Sets the initialized status.

    setInitialized(boolean $initialized)

Inherited

inherited_from | \BaseFilterReader::setInitialized()
inherited_from | \BaseParamFilterReader::setInitialized()

### Parameters

#### $initialized

`boolean`

Whether or not the filter is initialized.

## Sets the locale to use for translation.

    setLocale(string $locale)

Note that for gettext() to work, you have to make sure this locale is specific enough for your system (e.g. some systems may allow an 'en' locale, but others will require 'en_US', etc.).

### Parameters

#### $locale

`string`

## setParameters()

    setParameters($parameters)

Inherited

inherited_from | \BaseParamFilterReader::setParameters()

### Parameters

#### $parameters

## Sets the project to work with.

    setProject(\Project $project)

Inherited

inherited_from | \BaseFilterReader::setProject()
inherited_from | \BaseParamFilterReader::setProject()

### Parameters

#### $project

`object`

The project this filter is part of. Should not be `null`.

## setReader()

    setReader(\Reader $in)

Inherited

inherited_from | \FilterReader::setReader()
inherited_from | \BaseFilterReader::setReader()
inherited_from | \BaseParamFilterReader::setReader()

### Parameters

#### $in

## Move stream position relative to current pos.

    skip(int $n)

Inherited

inherited_from | \FilterReader::skip()
inherited_from | \BaseFilterReader::skip()
inherited_from | \BaseParamFilterReader::skip()

### Parameters

#### $n

`int`

## Make sure that required attributes are set.

    checkAttributes()

### Exceptions

`\BuldException` | - if any required attribs aren't set.

## Initialize the gettext/locale environment.

    initEnvironment() : void

This method will change some env vars and locale settings; the restoreEnvironment should put them all back :)

see | \global\restoreEnvironment()

### Exceptions

`\BuildException` | - if locale cannot be set.

## Restores environment settings and locale.

    restoreEnvironment() : void

This does not restore any gettext-specific settings (e.g. textdomain()).

## Parses the parameters if this filter is being used in "generic" mode.

    _initialize()

## Performs gettext translation of msgid and returns translated text.

    xlateStringCallback(array $matches) : string

This function simply wraps gettext() call, but provides ability to log string replacements. (alternative would be using preg_replace with /e which would probably be faster, but no ability to debug/log.)

### Parameters

#### $matches

`array`

Array of matches; we're interested in $matches[2].

### Returns

`string`Translated text

### Properties

##

    $_parameters

Inherited

inherited_from | \BaseParamFilterReader::$$_parameters

##

    $in : \Reader

Inherited

inherited_from | \FilterReader::$$in
inherited_from | \BaseFilterReader::$$in
inherited_from | \BaseParamFilterReader::$$in

##

    $initialized

Inherited

inherited_from | \BaseFilterReader::$$initialized
inherited_from | \BaseParamFilterReader::$$initialized

##

    $project

Inherited

inherited_from | \BaseFilterReader::$$project
inherited_from | \BaseParamFilterReader::$$project

##

    $dir

##

    $domain

##

    $locale

##

    $storedLocale

### Constants

## DIR_KEY

    DIR_KEY

## DOMAIN_KEY

    DOMAIN_KEY

## LOCALE_KEY

    LOCALE_KEY