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 953. 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:
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 954. 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.
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 955. 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
)
);
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
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
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 '_'
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.
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.
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.
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.