PhpRiot
Become Zend Certified

Prepare for the ZCE exam using our quizzes (web or iPad/iPhone). More info...


When you're ready get 7.5% off your exam voucher using voucher CJQNOV23 at the Zend Store

Automatic source detection

Zend_Translate can detect translation sources automatically. So you don't have to declare each source file manually. You can let Zend_Translate do this job and scan the complete directory structure for source files.

Note

Automatic source detection is available since Zend Framework version 1.5 .

The usage is quite the same as initiating a single translation source with one difference. You must give a directory which has to be scanned instead a file.

Example 972. Scanning a directory structure for sources

<?php
// assuming we have the following structure
//  /language/
//  /language/login/login.tmx
//  /language/logout/logout.tmx
//  /language/error/loginerror.tmx
//  /language/error/logouterror.tmx

$translate = new Zend_Translate(
    array(
'adapter' => 'tmx''content' => '/language')
);

So Zend_Translate does not only search the given directory, but also all subdirectories for translation source files. This makes the usage quite simple. But Zend_Translate will ignore all files which are not sources or which produce failures while reading the translation data. So you have to make sure that all of your translation sources are correct and readable because you will not get any failure if a file is bogus or can not be read.

Note

Depending on how deep your directory structure is and how much files are within this structure it can take a long time for Zend_Translate to complete.

In our example we have used the TMX format which includes the language to be used within the source. But many of the other source formats are not able to include the language within the file. Even this sources can be used with automatic scanning if you do some pre-requisits as described below:

Language through naming directories

One way to include automatic language detection is to name the directories related to the language which is used for the sources within this directory. This is the easiest way and is used for example within standard gettext implementations.

Zend_Translate needs the 'scan' option to know that it should search the names of all directories for languages. See the following example for details:

Example 973. Directory scanning for languages

<?php
// assuming we have the following structure
//  /language/
//  /language/de/login/login.mo
//  /language/de/error/loginerror.mo
//  /language/en/login/login.mo
//  /language/en/error/loginerror.mo

$translate = new Zend_Translate(
    array(
        
'adapter' => 'gettext',
        
'content' => '/language',
        
'scan' => Zend_Translate::LOCALE_DIRECTORY
    
)
);

Note

This works only for adapters which do not include the language within the source file. Using this option for example with TMX will be ignored. Also language definitions within the filename will be ignored when using this option.

Note

You should be aware if you have several subdirectories under the same structure. Assuming we have a structure like /language/module/de/en/file.mo. In this case the path contains multiple strings which would be detected as locale. It could be either de or en. In such a case the behaviour is undefined and it is recommended to use file detection in such situations.

Language through filenames

Another way to detect the language automatically is to use special filenames. You can either name the complete file or parts of a file after the used language. To use this way of detection you will have to set the 'scan' option at initiation. There are several ways of naming the sourcefiles which are described below:

Example 974. Filename scanning for languages

<?php
// assuming we have the following structure
//  /language/
//  /language/login/login_en.mo
//  /language/login/login_de.mo
//  /language/error/loginerror_en.mo
//  /language/error/loginerror_de.mo

$translate = new Zend_Translate(
    array(
        
'adapter' => 'gettext',
        
'content' => '/language',
        
'scan' => Zend_Translate::LOCALE_FILENAME
    
)
);

Complete filename

Having the whole file named after the language is the simplest way but only viable if you have only one file per language.

/languages/
/languages/en.mo
/languages/de.mo
/languages/es.mo
Extension of the file

Another simple way to use the extension of the file for language detection. But this may be confusing since you will no longer have an idea which extension the file originally had.

/languages/
/languages/view.en
/languages/view.de
/languages/view.es
Filename tokens

Zend_Translate is also capable of detecting the language if it is included within the filename. But if you go this way you will have to separate the language with a token. There are three supported tokens which can be used: a dot '.', an underscore '_', or a hyphen '-'.

/languages/
/languages/view_en.mo -> detects english
/languages/view_de.mo -> detects german
/languages/view_it.mo -> detects italian

The first found string delimited by a token which can be interpreted as a locale will be used. See the following example for details.

/languages/
/languages/view_en_de.mo -> detects english
/languages/view_en_es.mo -> detects english and overwrites the first file
/languages/view_it_it.mo -> detects italian

All three tokens are used to detect the locale. When the filename contains multiple tokens, the first found token depends on the order of the tokens which are used. See the following example for details.

/languages/
/languages/view_en-it.mo -> detects english because '_' will be used before '-'
/languages/view-en_it.mo -> detects italian because '_' will be used before '-'
/languages/view_en.it.mo -> detects italian because '.' will be used before '_'

Ignoring special files and directories

Sometimes it is useful to exclude files or even directories from being added automatically. Therefor you can use the ignore option which accepts 3 possible usages.

Ignore a special directory or file

Per default Zend_Translate is set to ignore all files and directories beginning with '/.'. This means that all SVN files will be ignored.

You can set your own syntax by giving a string for the ignore option. The directory separator will be attached automatically and has to be omitted.

<?php
$options   
= array('ignore' => 'test');
$translate = new Zend_Translate(
    array(
        
'adapter' => $adapter,
        
'content' => $content,
        
'locale'  => $locale,
        
'ignore'  => 'test'
    
)
);

The above example will ignore all files and directories beginning with test. This means for example /test/en.mo, /testing/en.mo and /dir/test_en.mo. But it would still add /mytest/en.mo or /dir/atest.mo.

Prevent SVN files from being searched

When you set this option, then the default '/.' will be erased. This means that Zend_Translate will then add all files from the hidden SVN directories. When you are working with SVN, then you should use the array syntax described in the next section.

Ignore several directories or files

You can also ignore several files and directories. Instead of a string, you can simply give an array with all wished names which will be ignored.

<?php
$options 
= array('ignore' => array('.''test''old'));
$translate = new Zend_Translate(
    array(
        
'adapter' => $adapter,
        
'content' => $content,
        
'locale'  => $locale,
        
'ignore'  => array('.''test''old')
    )
);

In the above case all 3 syntax will be ignored. But still they have to begin with the syntax to be detected and ignored.

Ignore specific names

To ignore files and directories which are not beginning with a defined syntax but have a special syntax anywhere within their name you can use a regular expression.

To use a regular expression the array key of the ignore option has to begin with regex.

<?php
$options 
= array(
    
'ignore' => array(
        
'regex' => '/test/u',
        
'regex_2' => '/deleted$/u'
    
)
);
$translate = new Zend_Translate(
    array(
        
'adapter' => $adapter,
        
'content' => $content,
        
'locale'  => $locale,
        
'ignore'  => array('regex' => '/test/u''regex_2' => '/deleted$/u')
    )
);

In the above case we defined 2 regular expressions. The files and directories will always being searched with all given regular expressions. In our example this means that any files which contains test anywhere in their name will be ignored. Additionally all files and directories which end with deleted will not be added as translation.

Zend Framework