## Apache Zeta Components Manual :: Docs For Class ezcTranslationTsBackend

### Translation::ezcTranslationTsBackend

### Class ezcTranslationTsBackend

Translation backend that reads Qt's Linguist TS files.

This class is the backend that can read Qt's Linguist files as source for a translation. The format is an XML file, which contains contexts and all the translatable strings.

Example:

1. <?php
2. $a=new ezcTranslationTsBackend (
3. 'tests/translations',
4. array('format'=>'[LOCALE].xml')
5. );
7. $b=new ezcTranslationManager ($a);
8. ?>

The reader capabilities of this class (the implementation of ezcTranslationContextRead) can be used it two different ways, where the second one is the more elegant approach.

Reader Example 1:

1. <?php
2. $backend=new ezcTranslationTsBackend ("files/translations");
3. $backend->options->format='[LOCALE].xml';
4. $backend-> initReader ('nb-no');
5. $backend-> next ();
7. $contexts=array();
8. while($backend-> valid () )
9. {
10. $contextName=$backend-> key ();
11. $contextData=$backend-> current ();
12. // do something with the data
13. $backend-> next ();
14. }
15. ?>

Reader Example 2:

1. <?php
2. $backend=new ezcTranslationTsBackend ("{$currentDir}/files/translations");
3. $backend->options->format='[LOCALE].xml';
4. $backend-> initReader ('nb-no');
6. $contexts=array();
7. foreach($backendas$contextName=>$contextData)
8. {
9. // do something with the data
10. }
11. ?>

For a more extensive example see ezcTranslationManager.

Source for this file: /Translation/src/backends/ts_backend.php

### Implements interfaces:

- ezcTranslationBackend
- ezcTranslationContextRead
- ezcTranslationContextWrite

Version: | //autogentag//

### Properties

ezcTranslationTsBackendOptions | read/write | `$options` Contains the options for this class.

### Member Variables

protected array(string=>mixed) | `$properties` Container to hold the properties

### Method Summary

public ezcTranslationTsBackend | `__construct( $location , [ $options = array()] )` Constructs a new ezcTranslationTsBackend that will use the file specified by $location.
public string | `buildTranslationFileName( $locale )` Returns the filename for the translation file using the locale $locale.
public array | `current( )` Returns the current context's data.
public array | `currentContext( )` Returns the current context
public void | `deinitReader( )` Deinitializes the reader
public void | `deinitWriter( )` Deinitializes the writer
public array(ezcTranslationData) | `getContext( $locale , $context )` Returns a array containing a translation map for the locale $locale and the context $context.
public array(string) | `getContextNames( $locale )` Returns a list with all context names for the locale $locale.
public ezcTranslationTsBackendOptions | `getOptions( )` Returns the current options.
public void | `initReader( $locale )` Initializes the reader to read from locale $locale.
public void | `initWriter( $locale )` Initializes the writer to write to locale $locale.
public string | `key( )` Returns the current context's name.
public void | `next( )` Advanced to the next context.
public object The | `openTranslationFile( $locale , [ $returnClass = 'SimpleXMLElement'] )` Creates an SimpleXML parser object for the locale $locale.
public object The | `openTranslationFileForWriting( $locale )` Creates a DOM parser object for the locale $locale.
public void | `rewind( )` Empty function to satisfy the Iterator interface.
public void | `setOptions( $options )` Set new options.
public void | `storeContext( $context , $data )` Stores a context.
public bool | `valid( )` Returns whether there is a new context available.

### Methods

#### __construct

ezcTranslationTsBackend __construct( string $location , [ $options = array()] )

Constructs a new ezcTranslationTsBackend that will use the file specified by $location.

You can specify additional options through the $options parameter. See the documentation for the ezcTranslationTsBackend::setOptions() method for supported options.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$location` | string |
`$options` | array(string=>mixed) |

##### Exceptions:

Type | Description
--- | ---
`ezcTranslationNotConfiguredException` | if $location is not set or is empty.

#### buildTranslationFileName

string buildTranslationFileName( string $locale )

Returns the filename for the translation file using the locale $locale.

This function uses the location and format options, combined with the $locale parameter to form a filename that contains the translation belonging to the specified locale.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$locale` | string |

#### current

array current( )

Returns the current context's data.

This method returns the latest read context, that the next() method put into the $currentContext property. See ezcTranslationTsBackend::$currentContext for the format of this array. This method is used for iteration as part of the Iterator interface.

##### Exceptions:

Type | Description
--- | ---
`ezcTranslationReaderNotInitializedException` | when the reader is not initialized with initReader().

#### currentContext

array currentContext( )

Returns the current context

This method returns the latest read context, that the haveMore() method put into the $currentContext property. See ezcTranslationTsBackend::$currentContext for the format of this array. This method is used for iteration as part of the Iterator interface.

##### Exceptions:

Type | Description
--- | ---
`ezcTranslationReaderNotInitializedException` | when the reader is not initialized with initReader().

#### deinitReader

void deinitReader( )

Deinitializes the reader

This method should be called after the haveMore() method returns false to cleanup resources.

##### Exceptions:

Type | Description
--- | ---
`ezcTranslationException` | when the reader is not initialized with initReader().

##### Implementation of:

Method | Description
--- | ---
`ezcTranslationContextRead::deinitReader()` | Deinitializes the reader.

#### deinitWriter

void deinitWriter( )

Deinitializes the writer

##### Implementation of:

Method | Description
--- | ---
`ezcTranslationContextWrite::deinitWriter()` | Deinitializes the writer

#### getContext

array(ezcTranslationData) getContext( string $locale , string $context )

Returns a array containing a translation map for the locale $locale and the context $context.

This method returns an array containing the translation map for the specified $locale and $context. It uses the location and format options to locate the file, unless caching is enabled.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$locale` | string |
`$context` | string |

##### Exceptions:

Type | Description
--- | ---
`ezcTranslationContextNotAvailableException` | if a context is not available
`ezcTranslationMissingTranslationFileException` | if the translation file does not exist.
`ezcTranslationNotConfiguredException` | if the option format is not set before this method is called.

##### Implementation of:

Method | Description
--- | ---
`ezcTranslationBackend::getContext()` | Returns an array with translation data for the context $context and the locale $locale.

#### getContextNames

array(string) getContextNames( string $locale )

Returns a list with all context names for the locale $locale.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$locale` | string |

##### Exceptions:

Type | Description
--- | ---
`ezcTranslationNotConfiguredException` | if the option format is not set before this method is called.
`ezcTranslationMissingTranslationFileException` | if the translation file does not exist.

#### getOptions

ezcTranslationTsBackendOptions getOptions( )

Returns the current options.

Returns the options currently set for this backend.

#### initReader

void initReader( string $locale )

Initializes the reader to read from locale $locale.

Opens the translation file.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$locale` | string |

##### Exceptions:

Type | Description
--- | ---
`ezcTranslationNotConfiguredException` | if the option format is not set before this method is called.

##### Implementation of:

Method | Description
--- | ---
`ezcTranslationContextRead::initReader()` | Initializes the reader to read from the locale $locale.

#### initWriter

void initWriter( string $locale )

Initializes the writer to write to locale $locale.

Opens the translation file.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$locale` | string |

##### Exceptions:

Type | Description
--- | ---
`ezcTranslationNotConfiguredException` | if the option format is not set before this method is called.

##### Implementation of:

Method | Description
--- | ---
`ezcTranslationContextWrite::initWriter()` | Initializes the writer to write from the locale $locale.

#### key

string key( )

Returns the current context's name.

This method returns the latest read context, that the next() method put into the $currentContext property. See ezcTranslationTsBackend::$currentContext for the format of this array. This method is used for iteration as part of the Iterator interface.

##### Exceptions:

Type | Description
--- | ---
`ezcTranslationReaderNotInitializedException` | when the reader is not initialized with initReader().

#### next

void next( )

Advanced to the next context.

This method parses a little bit more of the XML file to be able to return the next context. If no more contexts are available it sets the $currentContext member variable to null, so that the valid() method can pick this up. If there are more contexts available it reads the context from the file and stores it into the $currentContext member variable. This method is used for iteration as part of the Iterator interface.

##### Exceptions:

Type | Description
--- | ---
`ezcTranslationReaderNotInitializedException` | when the reader is not initialized with initReader().

#### openTranslationFile

object The openTranslationFile( string $locale , [string $returnClass = 'SimpleXMLElement'] )

Creates an SimpleXML parser object for the locale $locale.

You can set the class of the returned object through the $returnClass parameter. That class should extend the SimpleXMLElement class.

This function checks if the location setting is made, if the file with the filename as returned by buildTranslationFileName() exists and creates a SimpleXML parser object for this file. If either the setting is not made, or the file doesn't exists it throws an exception.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$locale` | string |
`$returnClass` | string | The class of the returned XML Parser Object.

##### Exceptions:

Type | Description
--- | ---
`ezcTranslationMissingTranslationFileException` | if the translation could not be opened.

#### openTranslationFileForWriting

object The openTranslationFileForWriting( string $locale )

Creates a DOM parser object for the locale $locale.

This function checks if the location setting is made, if the file with the filename as returned by buildTranslationFileName() exists and creates a DOM parser object for this file. If the setting is not made, it throws an exception. IF the file does not exist, a new DomDocument is created.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$locale` | string |

#### rewind

void rewind( )

Empty function to satisfy the Iterator interface.

The iterator interface expects this method to rewind to the start of the array. As we do not support rewinding actually, the only thing that the rewind() implementation does is reading the first element from the translation file. There are no side effects either if you just use the foreach or while methods. (See class introduction for an example). This method is used for iteration as part of the Iterator interface.

##### Exceptions:

Type | Description
--- | ---
`ezcTranslationReaderNotInitializedException` | when the reader is not initialized with initReader().

#### setOptions

void setOptions( ezcTranslationTsBackendOptions $options )

Set new options.

This method allows you to change the options of the translation backend.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$options` | ezcTranslationTsBackendOptions | The options to set.

##### Exceptions:

Type | Description
--- | ---
`ezcBaseSettingNotFoundException` | If you tried to set a non-existent option value.
`ezcBaseSettingValueException` | If the value is not valid for the desired option.
`ezcBaseValueException` | If you submit neither an array nor an instance of ezcTranslationTsBackendOptions.

##### Implementation of:

Method | Description
--- | ---
`ezcTranslationBackend::setOptions()` | Sets the backend specific $configurationData.

#### storeContext

void storeContext( string $context , $data )

Stores a context.

This method stores the context that it received to the backend specified storage place.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$context` | string | The context's name
`$data` | array(ezcTranslationData) | The context's translation map

##### Exceptions:

Type | Description
--- | ---
`ezcTranslationWriterNotInitializedException` | when the writer is not initialized with initWriter().

##### Implementation of:

Method | Description
--- | ---
`ezcTranslationContextWrite::storeContext()` | Stores the context named $context with the data $data.

#### valid

bool valid( )

Returns whether there is a new context available.

This method checks whether a valid context was read. It checks the $currentContext member variable for the status. This method is used for iteration as part of the Iterator interface.

##### Exceptions:

Type | Description
--- | ---
`ezcTranslationReaderNotInitializedException` | when the reader is not initialized with initReader().

Documentation generated by phpDocumentor 1.4.3