|
|
@@ -296,1016 +296,6 @@ print $translate->_(2) . "\n";
|
|
|
|
|
|
</sect2>
|
|
|
|
|
|
- <sect2 id="zend.translate.using.source.array">
|
|
|
-
|
|
|
- <title>Creating Array source files</title>
|
|
|
-
|
|
|
- <para>
|
|
|
- Array source files are plain arrays. But you have to define them
|
|
|
- manually since there is no tool to aid this.
|
|
|
- But because they are so simple, it's the fastest way to look up
|
|
|
- messages if your code works as expected. It's generally the best
|
|
|
- adapter to get started with translation business.
|
|
|
- </para>
|
|
|
-
|
|
|
- <programlisting language="php"><![CDATA[
|
|
|
-$english = array(
|
|
|
- 'message1' => 'message1',
|
|
|
- 'message2' => 'message2',
|
|
|
- 'message3' => 'message3');
|
|
|
-
|
|
|
-$german = array(
|
|
|
- 'message1' => 'Nachricht1',
|
|
|
- 'message2' => 'Nachricht2',
|
|
|
- 'message3' => 'Nachricht3');
|
|
|
-
|
|
|
-$translate = new Zend_Translate('array', $english, 'en');
|
|
|
-$translate->addTranslation($deutsch, 'de');
|
|
|
-]]></programlisting>
|
|
|
-
|
|
|
- <para>
|
|
|
- Since release 1.5 it is also supported to have arrays included within an external file.
|
|
|
- You just have to provide the filename and <classname>Zend_Translate</classname> will automatically
|
|
|
- include it and look for the array. See the following example for details:
|
|
|
- </para>
|
|
|
-
|
|
|
- <programlisting language="php"><![CDATA[
|
|
|
-// myarray.php
|
|
|
-return array(
|
|
|
- 'message1' => 'Nachricht1',
|
|
|
- 'message2' => 'Nachricht2',
|
|
|
- 'message3' => 'Nachricht3');
|
|
|
-
|
|
|
-// controller
|
|
|
-$translate = new Zend_Translate('array', '/path/to/myarray.php', 'de');
|
|
|
-]]></programlisting>
|
|
|
-
|
|
|
- <note>
|
|
|
- <para>
|
|
|
- Files which do not return an array will fail to be included.
|
|
|
- Also any output within this file will be ignored and suppressed.
|
|
|
- </para>
|
|
|
-
|
|
|
- </note>
|
|
|
-
|
|
|
- </sect2>
|
|
|
-
|
|
|
- <sect2 id="zend.translate.using.source.gettext">
|
|
|
-
|
|
|
- <title>Creating Gettext source files</title>
|
|
|
-
|
|
|
- <para>
|
|
|
- Gettext source files are created by GNU's gettext library.
|
|
|
- There are several free tools available that can parse your
|
|
|
- code files and create the needed gettext source files.
|
|
|
- These have the extension <emphasis>*.mo</emphasis>
|
|
|
- and they are binary files.
|
|
|
- An open source tool for creating the files is
|
|
|
- <ulink url="http://sourceforge.net/projects/poedit/">poEdit</ulink>.
|
|
|
- This tool also supports you during the translation process itself.
|
|
|
- </para>
|
|
|
-
|
|
|
- <programlisting language="php"><![CDATA[
|
|
|
-// We accume that we have created the mo files and translated them
|
|
|
-$translate = new Zend_Translate('gettext', '/path/to/english.mo', 'en');
|
|
|
-$translate->addTranslation('/path/to/german.mo', 'de');
|
|
|
-]]></programlisting>
|
|
|
-
|
|
|
- <para>
|
|
|
- As you can see the adapters are used exactly the same way,
|
|
|
- with one small difference:
|
|
|
- change <emphasis>array</emphasis> to <emphasis>gettext</emphasis>. All other usages are exactly
|
|
|
- the same as with all other adapters.
|
|
|
- With the gettext adapter you no longer have to be aware of
|
|
|
- gettext's standard directory structure,
|
|
|
- bindtextdomain and textdomain.
|
|
|
- Just give the path and filename to the adapter.
|
|
|
- </para>
|
|
|
-
|
|
|
- <note>
|
|
|
- <para>
|
|
|
- You should always use UTF-8 as source encoding.
|
|
|
- Otherwise you will have problems when using two
|
|
|
- different source encodings.
|
|
|
- E.g. one of your source files is encoded
|
|
|
- with ISO-8815-11 and another one with CP815.
|
|
|
- You can set only one encoding for your source file,
|
|
|
- so one of your languages probably will not display correctly.
|
|
|
- </para>
|
|
|
- <para>
|
|
|
- UTF-8 is a portable format which supports all languages.
|
|
|
- When using UTF-8 for all languages, you will eliminate
|
|
|
- the problem of incompatible encodings.
|
|
|
- </para>
|
|
|
- </note>
|
|
|
-
|
|
|
- <para>
|
|
|
- Many gettext editors add adapter informations as empty translation string.
|
|
|
- This is the reason why empty strings are not translated when using the
|
|
|
- gettext adapter. Instead they are erased from the translation table and
|
|
|
- provided by the <code>getAdapterInfo()</code> method. It will return
|
|
|
- the adapter informations for all added gettext files as array using the
|
|
|
- filename as key.
|
|
|
- </para>
|
|
|
-
|
|
|
- <programlisting language="php"><![CDATA[
|
|
|
-// Getting the adapter informations
|
|
|
-$translate = new Zend_Translate('gettext', '/path/to/english.mo', 'en');
|
|
|
-print_r($translate->getAdapterInfo());
|
|
|
-]]></programlisting>
|
|
|
-
|
|
|
- </sect2>
|
|
|
-
|
|
|
- <sect2 id="zend.translate.using.source.tmx">
|
|
|
-
|
|
|
- <title>Creating TMX source files</title>
|
|
|
-
|
|
|
- <para>
|
|
|
- TMX source files are a new industry standard.
|
|
|
- They have the advantage of being XML files and so they are
|
|
|
- readable by every editor and of course by humans.
|
|
|
- You can either create TMX files manually with a text editor,
|
|
|
- or you can use a special tool. But most tools currently available for
|
|
|
- creating TMX source files are not freely available.
|
|
|
- </para>
|
|
|
-
|
|
|
- <example id="zend.translate.using.source.tmx.example">
|
|
|
- <title>Example TMX file</title>
|
|
|
- <programlisting language="xml"><![CDATA[
|
|
|
-<?xml version="1.0" ?>
|
|
|
-<!DOCTYPE tmx SYSTEM "tmx14.dtd">
|
|
|
-<tmx version="1.4">
|
|
|
- <header creationtoolversion="1.0.0" datatype="winres" segtype="sentence"
|
|
|
- adminlang="en-us" srclang="de-at" o-tmf="abc"
|
|
|
- creationtool="XYZTool" >
|
|
|
- </header>
|
|
|
- <body>
|
|
|
- <tu tuid='message1'>
|
|
|
- <tuv xml:lang="de"><seg>Nachricht1</seg></tuv>
|
|
|
- <tuv xml:lang="en"><seg>message1</seg></tuv>
|
|
|
- </tu>
|
|
|
- <tu tuid='message2'>
|
|
|
- <tuv xml:lang="en"><seg>message2</seg></tuv>
|
|
|
- <tuv xml:lang="de"><seg>Nachricht2</seg></tuv>
|
|
|
- </tu>
|
|
|
-]]></programlisting>
|
|
|
-
|
|
|
- <programlisting language="php"><![CDATA[
|
|
|
-$translate = new Zend_Translate('tmx', 'path/to/mytranslation.tmx', 'en');
|
|
|
-]]></programlisting>
|
|
|
- </example>
|
|
|
-
|
|
|
- <para>
|
|
|
- TMX files can have several languages within the same file.
|
|
|
- All other included languages are added automatically,
|
|
|
- so you do not have to call <code>addLanguage()</code>.
|
|
|
- </para>
|
|
|
-
|
|
|
- <para>
|
|
|
- If you want to have only specified languages from the source translated
|
|
|
- you can set the option '<code>defined_language</code>' to <constant>TRUE</constant>.
|
|
|
- With this option you can add the wished languages explicitly with
|
|
|
- <code>addLanguage()</code>. The default value for this option is to add all
|
|
|
- languages.
|
|
|
- </para>
|
|
|
- </sect2>
|
|
|
-
|
|
|
- <sect2 id="zend.translate.using.source.csv">
|
|
|
-
|
|
|
- <title>Creating CSV source files</title>
|
|
|
-
|
|
|
- <para>
|
|
|
- CSV source files are small and human readable.
|
|
|
- If your customers want to translate their own,
|
|
|
- you will probably use the CSV adapter.
|
|
|
- </para>
|
|
|
-
|
|
|
- <example id="zend.translate.using.source.csv.example">
|
|
|
- <title>Example CSV file</title>
|
|
|
- <programlisting language="txt"><![CDATA[
|
|
|
-#Example csv file
|
|
|
-message1;Nachricht1
|
|
|
-message2;Nachricht2
|
|
|
-]]></programlisting>
|
|
|
-
|
|
|
- <programlisting language="php"><![CDATA[
|
|
|
-$translate = new Zend_Translate('csv', '/path/to/mytranslation.csv', 'de');
|
|
|
-$translate->addTranslation('path/to/other.csv', 'fr');
|
|
|
-]]></programlisting>
|
|
|
- </example>
|
|
|
-
|
|
|
- <para>
|
|
|
- There are three different options for the CSV adapter.
|
|
|
- You can set '<code>delimiter</code>', '<code>limit</code>' and
|
|
|
- '<code>enclosure</code>'.
|
|
|
- </para>
|
|
|
-
|
|
|
- <para>
|
|
|
- The default delimiter for CSV string is '<code>;</code>', but
|
|
|
- with the option '<code>delimiter</code>'
|
|
|
- you can decide to use another one.
|
|
|
- </para>
|
|
|
-
|
|
|
- <para>
|
|
|
- The default limit for a line within a CSV file is '<code>0</code>'. This means
|
|
|
- that the end of a CSV line is searched automatically. If you set
|
|
|
- '<code>limit</code>' to any value, then the CSV file will be
|
|
|
- read faster, but any line exceeding this limit will be truncated.
|
|
|
- </para>
|
|
|
-
|
|
|
- <para>
|
|
|
- The default enclosure to use for CSV files is '<code>"</code>'. You can
|
|
|
- set a different one using the option '<code>enclosure</code>'.
|
|
|
- </para>
|
|
|
-
|
|
|
- <example id="zend.translate.using.source.csv.example2">
|
|
|
- <title>Second CSV file example</title>
|
|
|
- <programlisting language="txt"><![CDATA[
|
|
|
-# Example CSV file
|
|
|
-"message,1",Nachricht1
|
|
|
-message2,"Nachricht,2"
|
|
|
-"message3,",Nachricht3
|
|
|
-]]></programlisting>
|
|
|
-
|
|
|
- <programlisting language="php"><![CDATA[
|
|
|
-$translate = new Zend_Translate(
|
|
|
- 'csv',
|
|
|
- '/path/to/mytranslation.csv',
|
|
|
- 'de',
|
|
|
- array('delimiter' => ','));
|
|
|
-
|
|
|
-$translate->addTranslation('/path/to/other.csv', 'fr');
|
|
|
-]]></programlisting>
|
|
|
- </example>
|
|
|
-
|
|
|
- </sect2>
|
|
|
-
|
|
|
- <sect2 id="zend.translate.using.source.ini">
|
|
|
-
|
|
|
- <title>Creating INI source files</title>
|
|
|
-
|
|
|
- <para>
|
|
|
- INI source files are human readable but normally not very small as they also
|
|
|
- include other data beside translations. If you have data which shall be
|
|
|
- editable by your customers you can use the INI adapter.
|
|
|
- </para>
|
|
|
-
|
|
|
- <example id="zend.translate.using.source.ini.example">
|
|
|
- <title>Example INI file</title>
|
|
|
- <programlisting language="txt"><![CDATA[
|
|
|
-[Test]
|
|
|
-;TestPage Comment
|
|
|
-Message_1="Nachricht 1 (de)"
|
|
|
-Message_2="Nachricht 2 (de)"
|
|
|
-Message_3="Nachricht :3 (de)"
|
|
|
-]]></programlisting>
|
|
|
-
|
|
|
- <programlisting language="php"><![CDATA[
|
|
|
-$translate = new Zend_Translate('ini', '/path/to/mytranslation.ini', 'de');
|
|
|
-$translate->addTranslation('/path/to/other.ini', 'it');
|
|
|
-]]></programlisting>
|
|
|
- </example>
|
|
|
-
|
|
|
- <para>
|
|
|
- INI files have several restrictions. If a value in the ini file contains any
|
|
|
- non-alphanumeric characters it needs to be enclosed in double-quotes (<code>"</code>).
|
|
|
- There are also reserved words which must not be used as keys for ini files.
|
|
|
- These include: <constant>NULL</constant>, <code>yes</code>, <code>no</code>, <constant>TRUE</constant>,
|
|
|
- and <constant>FALSE</constant>. Values <constant>NULL</constant>, <code>no</code> and <constant>FALSE</constant> results
|
|
|
- in <code>""</code>, <code>yes</code> and <constant>TRUE</constant> results in <code>1</code>. Characters <code>{}|&~![()"</code> must not be used anywhere
|
|
|
- in the key and have a special meaning in the value. Do not use them as it will
|
|
|
- produce unexpected behaviour.
|
|
|
- </para>
|
|
|
-
|
|
|
- </sect2>
|
|
|
-
|
|
|
- <sect2 id="zend.translate.using.options">
|
|
|
-
|
|
|
- <title>Options for adapters</title>
|
|
|
-
|
|
|
- <para>
|
|
|
- Options can be used with all adapters. Of course the options are different for all adapters.
|
|
|
- You can set options when you create the adapter. Actually there is one option which is available
|
|
|
- to all adapters: '<code>clear</code>' sets if translation data should be added to existing
|
|
|
- one or not. Standard behaviour is to add new translation data to existing one. But the
|
|
|
- translation data is only cleared for the selected language. So other languages remain
|
|
|
- untouched.
|
|
|
- </para>
|
|
|
-
|
|
|
- <para>
|
|
|
- You can set options temporarily when using <code>addTranslation($data, $locale, array $options = array())</code>
|
|
|
- as third and optional parameter. And you can use the method <code>setOptions()</code> to
|
|
|
- set the options permanently.
|
|
|
- </para>
|
|
|
-
|
|
|
- <example id="zend.translate.using.options.example">
|
|
|
- <title>Using translation options</title>
|
|
|
- <programlisting language="php"><![CDATA[
|
|
|
-// define ':' as separator for the translation source files
|
|
|
-$options = array('delimiter' => ':');
|
|
|
-$translate = new Zend_Translate(
|
|
|
- 'csv',
|
|
|
- '/path/to/mytranslation.csv',
|
|
|
- 'de',
|
|
|
- $options);
|
|
|
-
|
|
|
-...
|
|
|
-
|
|
|
-// clear the defined language and use new translation data
|
|
|
-$options = array('clear' => true);
|
|
|
-$translate->addTranslation('/path/to/new.csv', 'fr', $options);
|
|
|
-]]></programlisting>
|
|
|
- </example>
|
|
|
-
|
|
|
- <para>
|
|
|
- Here you can find all available options for the different adapters with a description of their usage:
|
|
|
- </para>
|
|
|
-
|
|
|
- <table id="zend.translate.using.options.alloptions">
|
|
|
- <title>Options for translation adapters</title>
|
|
|
- <tgroup cols="4">
|
|
|
- <thead>
|
|
|
- <row>
|
|
|
- <entry>Option</entry>
|
|
|
- <entry>Adapter</entry>
|
|
|
- <entry>Description</entry>
|
|
|
- <entry>Default value</entry>
|
|
|
- </row>
|
|
|
- </thead>
|
|
|
- <tbody>
|
|
|
- <row>
|
|
|
- <entry>clear</entry>
|
|
|
- <entry>all</entry>
|
|
|
- <entry>
|
|
|
- If set to true, the already read translations will be cleared. This can be used
|
|
|
- instead of creating a new instance when reading new translation data
|
|
|
- </entry>
|
|
|
- <entry><emphasis>false</emphasis></entry>
|
|
|
- </row>
|
|
|
- <row>
|
|
|
- <entry>disableNotices</entry>
|
|
|
- <entry>all</entry>
|
|
|
- <entry>
|
|
|
- If set to true, all notices regarding not available translations will be
|
|
|
- disabled. You should set this option to true in production environment
|
|
|
- </entry>
|
|
|
- <entry><emphasis>false</emphasis></entry>
|
|
|
- </row>
|
|
|
- <row>
|
|
|
- <entry>ignore</entry>
|
|
|
- <entry>all</entry>
|
|
|
- <entry>
|
|
|
- All directories and files beginning with this prefix will be ignored when
|
|
|
- searching for files. This value defaults to <emphasis>'.'</emphasis>
|
|
|
- which leads to the behavior that all hidden files will be ignored. Setting this
|
|
|
- value to <code>'tmp'</code> would mean that directories and files like
|
|
|
- <code>'tmpImages'</code> and <code>'tmpFiles'</code>
|
|
|
- would be ignored as well as all subsequent directories
|
|
|
- </entry>
|
|
|
- <entry><emphasis>.</emphasis></entry>
|
|
|
- </row>
|
|
|
- <row>
|
|
|
- <entry>log</entry>
|
|
|
- <entry>all</entry>
|
|
|
- <entry>
|
|
|
- An instance of <classname>Zend_Log</classname> where untranslated messages and notices will be
|
|
|
- written to
|
|
|
- </entry>
|
|
|
- <entry><emphasis>null</emphasis></entry>
|
|
|
- </row>
|
|
|
- <row>
|
|
|
- <entry>logMessage</entry>
|
|
|
- <entry>all</entry>
|
|
|
- <entry>
|
|
|
- The message which will be written into the log
|
|
|
- </entry>
|
|
|
- <entry><emphasis>Untranslated message within '%locale%': %message%</emphasis></entry>
|
|
|
- </row>
|
|
|
- <row>
|
|
|
- <entry>logUntranslated</entry>
|
|
|
- <entry>all</entry>
|
|
|
- <entry>
|
|
|
- When this option is set to true, all message IDs which can not be
|
|
|
- translated will be written into the attached log
|
|
|
- </entry>
|
|
|
- <entry><emphasis>false</emphasis></entry>
|
|
|
- </row>
|
|
|
- <row>
|
|
|
- <entry>scan</entry>
|
|
|
- <entry>all</entry>
|
|
|
- <entry>
|
|
|
- If set to null, no scanning of the directory structure will be done.
|
|
|
- If set to <classname>Zend_Translate::LOCALE_DIRECTORY</classname> the locale will be detected within the
|
|
|
- directory. If set to <classname>Zend_Translate::LOCALE_FILENAME</classname> the locale will be detected
|
|
|
- within the filename. See <xref linkend="zend.translate.using.detection" />
|
|
|
- for details
|
|
|
- </entry>
|
|
|
- <entry><emphasis>null</emphasis></entry>
|
|
|
- </row>
|
|
|
- <row>
|
|
|
- <entry>delimiter</entry>
|
|
|
- <entry>Csv</entry>
|
|
|
- <entry>Defines which sign is used as delimiter for separating source and translation</entry>
|
|
|
- <entry><emphasis>;</emphasis></entry>
|
|
|
- </row>
|
|
|
- <row>
|
|
|
- <entry>enclosure</entry>
|
|
|
- <entry>Csv</entry>
|
|
|
- <entry>Defines the enclosure character to be used. Defaults to a doublequote</entry>
|
|
|
- <entry><emphasis>"</emphasis></entry>
|
|
|
- </row>
|
|
|
- <row>
|
|
|
- <entry>length</entry>
|
|
|
- <entry>Csv</entry>
|
|
|
- <entry>Defines the maximum length of a csv line. When set to 0 it will be detected automatically</entry>
|
|
|
- <entry><emphasis>0</emphasis></entry>
|
|
|
- </row>
|
|
|
- </tbody>
|
|
|
- </tgroup>
|
|
|
- </table>
|
|
|
-
|
|
|
- <para>
|
|
|
- When you want to have self defined options, you are also able to use them within all adapters.
|
|
|
- The <code>setOptions()</code> method can be used to define your option. <code>setOptions()</code>
|
|
|
- needs an array with the options you want to set. If an given option exists it will be signed over.
|
|
|
- You can define as much options as needed as they will not be checked by the adapter. Just make sure
|
|
|
- not to overwrite any existing option which is used by an adapter.
|
|
|
- </para>
|
|
|
-
|
|
|
- <para>
|
|
|
- To return the option you can use the <code>getOptions()</code> method. When <code>getOptions()</code>
|
|
|
- is called without a parameter it will return all options set. When the optional parameter is given
|
|
|
- you will only get the specified option.
|
|
|
- </para>
|
|
|
-
|
|
|
- </sect2>
|
|
|
-
|
|
|
- <sect2 id="zend.translate.using.languages">
|
|
|
-
|
|
|
- <title>Handling languages</title>
|
|
|
-
|
|
|
- <para>
|
|
|
- When working with different languages there are a few methods which will be useful.
|
|
|
- </para>
|
|
|
-
|
|
|
- <para>
|
|
|
- The <code>getLocale()</code> method can be used to get the currently set language. It can either hold
|
|
|
- an instance of <classname>Zend_Locale</classname> or the identifier of a locale.
|
|
|
- </para>
|
|
|
-
|
|
|
- <para>
|
|
|
- The <code>setLocale()</code> method sets a new standard language for translation. This prevents the
|
|
|
- need of setting the optional language parameter more than once to the <code>translate()</code> method.
|
|
|
- If the given language does not exist, or no translation data is available for the language,
|
|
|
- <code>setLocale()</code> tries to downgrade to the language without the region if any was given.
|
|
|
- A language of <code>en_US</code> would be downgraded to <code>en</code>. When even the downgraded
|
|
|
- language can not be found an exception will be thrown.
|
|
|
- </para>
|
|
|
-
|
|
|
- <para>
|
|
|
- The <code>isAvailable()</code> method checks if a given language is already available. It returns
|
|
|
- <constant>TRUE</constant> if data for the given language exist.
|
|
|
- </para>
|
|
|
-
|
|
|
- <para>
|
|
|
- And finally the <code>getList()</code> method can be used to get all currently set languages for an adapter
|
|
|
- returned as array.
|
|
|
- </para>
|
|
|
-
|
|
|
- <example id="zend.translate.using.languages.example">
|
|
|
- <title>Handling languages with adapters</title>
|
|
|
- <programlisting language="php"><![CDATA[
|
|
|
-// returns the currently set language
|
|
|
-$actual = $translate->getLocale();
|
|
|
-
|
|
|
-// you can use the optional parameter while translating
|
|
|
-echo $translate->_("my_text", "fr");
|
|
|
-// or set a new language
|
|
|
-$translate->setLocale("fr");
|
|
|
-echo $translate->_("my_text");
|
|
|
-// refer to the base language
|
|
|
-// fr_CH will be downgraded to fr
|
|
|
-$translate->setLocale("fr_CH");
|
|
|
-echo $translate->_("my_text");
|
|
|
-
|
|
|
-// check if this language exist
|
|
|
-if ($translate->isAvailable("fr")) {
|
|
|
- // language exists
|
|
|
-}
|
|
|
-]]></programlisting>
|
|
|
- </example>
|
|
|
-
|
|
|
- <sect3 id="zend.translate.using.languages.automatic">
|
|
|
-
|
|
|
- <title>Automatical handling of languages</title>
|
|
|
-
|
|
|
- <para>
|
|
|
- Note that as long as you only add new translation sources with the <code>addTranslation()</code>
|
|
|
- method <classname>Zend_Translate</classname> will automatically set the best fitting language for your
|
|
|
- environment when you use one of the automatic locales which are '<code>auto</code>' or '<code>browser</code>'. So
|
|
|
- normally you will not need to call <code>setLocale()</code>. This should only be used in
|
|
|
- conjunction with automatic source detection.
|
|
|
- </para>
|
|
|
-
|
|
|
- <para>
|
|
|
- The algorithm will search for the best fitting locale depending on the user's browser and
|
|
|
- your environment. See the following example for details:
|
|
|
- </para>
|
|
|
-
|
|
|
- <example id="zend.translate.using.languages.automatic.example">
|
|
|
- <title>Automatically language detection</title>
|
|
|
- <programlisting language="php"><![CDATA[
|
|
|
-// Let's expect the browser returns these language settings:
|
|
|
-// HTTP_ACCEPT_LANGUAGE = "de_AT=1;fr=1;en_US=0.8";
|
|
|
-
|
|
|
-// Example 1:
|
|
|
-// When no fitting language is found, the message ID is returned
|
|
|
-$translate = new Zend_Translate(
|
|
|
- 'gettext',
|
|
|
- 'my_it.mo',
|
|
|
- 'auto',
|
|
|
- array('scan' => Zend_Translate::LOCALE_FILENAME));
|
|
|
-
|
|
|
-// Example 2:
|
|
|
-// Best found fitting language is 'fr'
|
|
|
-$translate = new Zend_Translate(
|
|
|
- 'gettext',
|
|
|
- 'my_fr.mo',
|
|
|
- 'auto',
|
|
|
- array('scan' => Zend_Translate::LOCALE_FILENAME));
|
|
|
-
|
|
|
-// Example 3:
|
|
|
-// Best found fitting language is 'de' ('de_AT' will be degraded)
|
|
|
-$translate = new Zend_Translate(
|
|
|
- 'gettext',
|
|
|
- 'my_de.mo',
|
|
|
- 'auto',
|
|
|
- array('scan' => Zend_Translate::LOCALE_FILENAME));
|
|
|
-
|
|
|
-// Example 4:
|
|
|
-// Returns 'it' as translation source and overrides the automatic settings
|
|
|
-$translate = new Zend_Translate(
|
|
|
- 'gettext',
|
|
|
- 'my_it.mo',
|
|
|
- 'auto',
|
|
|
- array('scan' => Zend_Translate::LOCALE_FILENAME));
|
|
|
-
|
|
|
-$translate->addTranslation('my_ru.mo', 'ru');
|
|
|
-$translate->setLocale('it_IT');
|
|
|
-]]></programlisting>
|
|
|
- </example>
|
|
|
-
|
|
|
- <para>
|
|
|
- After setting a language manually with the <code>setLocale()</code> method the automatic
|
|
|
- detection will be switched off and overridden.
|
|
|
- </para>
|
|
|
-
|
|
|
- <para>
|
|
|
- If you want to use it again, you can set the language
|
|
|
- <emphasis>auto</emphasis> with <code>setLocale()</code> which will reactivate
|
|
|
- the automatic detection for <classname>Zend_Translate</classname>.
|
|
|
- </para>
|
|
|
-
|
|
|
- <para>
|
|
|
- Since Zend Framework 1.7.0 <classname>Zend_Translate</classname> also recognises an application
|
|
|
- wide locale. You can simply set a <classname>Zend_Locale</classname> instance to the registry like shown
|
|
|
- below. With this notation you can forget about setting the locale manually with each instance
|
|
|
- when you want to use the same locale multiple times.
|
|
|
- </para>
|
|
|
-
|
|
|
- <programlisting language="php"><![CDATA[
|
|
|
-// in your bootstrap file
|
|
|
-$locale = new Zend_Locale();
|
|
|
-Zend_Registry::set('Zend_Locale', $locale);
|
|
|
-
|
|
|
-// default language when requested language is not available
|
|
|
-$defaultlanguage = 'en';
|
|
|
-
|
|
|
-// somewhere in your application
|
|
|
-$translate = new Zend_Translate('gettext', 'my_de.mo');
|
|
|
-
|
|
|
-if (!$translate->isAvailable($locale->getLanguage())) {
|
|
|
- // not available languages are rerouted to another language
|
|
|
- $translate->setLocale($defaultlanguage);
|
|
|
-}
|
|
|
-
|
|
|
-$translate->getLocale();
|
|
|
-]]></programlisting>
|
|
|
-
|
|
|
- </sect3>
|
|
|
-
|
|
|
- </sect2>
|
|
|
-
|
|
|
- <sect2 id="zend.translate.using.detection">
|
|
|
-
|
|
|
- <title>Automatic source detection</title>
|
|
|
-
|
|
|
- <para>
|
|
|
- <classname>Zend_Translate</classname> can detect translation sources automatically. So you don't have
|
|
|
- to declare each source file manually. You can let <classname>Zend_Translate</classname> do this job and
|
|
|
- scan the complete directory structure for source files.
|
|
|
- </para>
|
|
|
-
|
|
|
- <note>
|
|
|
- <para>
|
|
|
- Automatic source detection is available since Zend Framework version 1.5 .
|
|
|
- </para>
|
|
|
- </note>
|
|
|
-
|
|
|
- <para>
|
|
|
- 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.
|
|
|
- </para>
|
|
|
-
|
|
|
- <example id="zend.translate.using.languages.directory.example">
|
|
|
- <title>Scanning a directory structure for sources</title>
|
|
|
- <programlisting language="php"><![CDATA[
|
|
|
-// 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('tmx', '/language');
|
|
|
-]]></programlisting>
|
|
|
- </example>
|
|
|
-
|
|
|
- <para>
|
|
|
- So <classname>Zend_Translate</classname> does not only search the given directory, but also all subdirectories for
|
|
|
- translation source files. This makes the usage quite simple. But <classname>Zend_Translate</classname> 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.
|
|
|
- </para>
|
|
|
-
|
|
|
- <note>
|
|
|
- <para>
|
|
|
- Depending on how deep your directory structure is and how much files are within this structure
|
|
|
- it can take a long time for <classname>Zend_Translate</classname> to complete.
|
|
|
- </para>
|
|
|
- </note>
|
|
|
-
|
|
|
- <para>
|
|
|
- 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:
|
|
|
- </para>
|
|
|
-
|
|
|
- <sect3 id="zend.translate.using.detection.directory">
|
|
|
-
|
|
|
- <title>Language through naming directories</title>
|
|
|
-
|
|
|
- <para>
|
|
|
- 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.
|
|
|
- </para>
|
|
|
-
|
|
|
- <para>
|
|
|
- <classname>Zend_Translate</classname> needs the '<code>scan</code>' option to know that it should search the names of all
|
|
|
- directories for languages. See the following example for details:
|
|
|
- </para>
|
|
|
-
|
|
|
- <example id="zend.translate.using.detection.directory.example">
|
|
|
- <title>Directory scanning for languages</title>
|
|
|
- <programlisting language="php"><![CDATA[
|
|
|
-// 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(
|
|
|
- 'gettext',
|
|
|
- '/language',
|
|
|
- null,
|
|
|
- array('scan' => Zend_Translate::LOCALE_DIRECTORY));
|
|
|
-]]></programlisting>
|
|
|
- </example>
|
|
|
-
|
|
|
- <note>
|
|
|
- <para>
|
|
|
- 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.
|
|
|
- </para>
|
|
|
- </note>
|
|
|
-
|
|
|
- <note>
|
|
|
- <para>
|
|
|
- You should be aware if you have several subdirectories under the same
|
|
|
- structure. Assuming we have a structure like
|
|
|
- <code>/language/module/de/en/file.mo</code>. In this case the path contains
|
|
|
- multiple strings which would be detected as locale. It could be either
|
|
|
- <code>de</code> or <code>en</code>. In such a case the behaviour is
|
|
|
- undefined and it is recommended to use file detection in such situations.
|
|
|
- </para>
|
|
|
- </note>
|
|
|
-
|
|
|
- </sect3>
|
|
|
-
|
|
|
- <sect3 id="zend.translate.using.detection.filename">
|
|
|
-
|
|
|
- <title>Language through filenames</title>
|
|
|
-
|
|
|
- <para>
|
|
|
- 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 '<code>scan</code>' option at initiation. There are several ways of naming the
|
|
|
- sourcefiles which are described below:
|
|
|
- </para>
|
|
|
-
|
|
|
- <example id="zend.translate.using.detection.filename.example">
|
|
|
- <title>Filename scanning for languages</title>
|
|
|
- <programlisting language="php"><![CDATA[
|
|
|
-// 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(
|
|
|
- 'gettext',
|
|
|
- '/language',
|
|
|
- null,
|
|
|
- array('scan' => Zend_Translate::LOCALE_FILENAME));
|
|
|
-]]></programlisting>
|
|
|
- </example>
|
|
|
-
|
|
|
- <sect4 id="zend.translate.using.detection.filename.complete">
|
|
|
-
|
|
|
- <title>Complete filename</title>
|
|
|
-
|
|
|
- <para>
|
|
|
- Having the whole file named after the language is the simplest way but only viable
|
|
|
- if you have only one file per language.
|
|
|
- </para>
|
|
|
-
|
|
|
- <programlisting language="txt"><![CDATA[
|
|
|
-/languages/
|
|
|
-/languages/en.mo
|
|
|
-/languages/de.mo
|
|
|
-/languages/es.mo
|
|
|
-]]></programlisting>
|
|
|
-
|
|
|
- </sect4>
|
|
|
-
|
|
|
- <sect4 id="zend.translate.using.detection.filename.extension">
|
|
|
-
|
|
|
- <title>Extension of the file</title>
|
|
|
-
|
|
|
- <para>
|
|
|
- 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.
|
|
|
- </para>
|
|
|
-
|
|
|
- <programlisting language="txt"><![CDATA[
|
|
|
-/languages/
|
|
|
-/languages/view.en
|
|
|
-/languages/view.de
|
|
|
-/languages/view.es
|
|
|
-]]></programlisting>
|
|
|
-
|
|
|
- </sect4>
|
|
|
-
|
|
|
- <sect4 id="zend.translate.using.detection.filename.token">
|
|
|
-
|
|
|
- <title>Filename tokens</title>
|
|
|
-
|
|
|
- <para>
|
|
|
- <classname>Zend_Translate</classname> 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 '-'.
|
|
|
- </para>
|
|
|
-
|
|
|
- <programlisting language="txt"><![CDATA[
|
|
|
-/languages/
|
|
|
-/languages/view_en.mo -> detects english
|
|
|
-/languages/view_de.mo -> detects german
|
|
|
-/languages/view_it.mo -> detects italian
|
|
|
-]]></programlisting>
|
|
|
-
|
|
|
- <para>
|
|
|
- The first found string delimited by a token which can be interpreted as a locale will be used. See the following
|
|
|
- example for details.
|
|
|
- </para>
|
|
|
-
|
|
|
- <programlisting language="txt"><![CDATA[
|
|
|
-/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
|
|
|
-]]></programlisting>
|
|
|
-
|
|
|
- <para>
|
|
|
- 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.
|
|
|
- </para>
|
|
|
-
|
|
|
- <programlisting language="txt"><![CDATA[
|
|
|
-/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 '_'
|
|
|
-]]></programlisting>
|
|
|
-
|
|
|
- </sect4>
|
|
|
-
|
|
|
- </sect3>
|
|
|
-
|
|
|
- </sect2>
|
|
|
-
|
|
|
- <sect2 id="zend.translate.using.istranslated">
|
|
|
-
|
|
|
- <title>Checking for translations</title>
|
|
|
-
|
|
|
- <para>
|
|
|
- Normally text will be translated without any computation. But sometimes it is necessary to
|
|
|
- know if a text is translated or not, therefor the <code>isTranslated()</code>
|
|
|
- method can be used.
|
|
|
- </para>
|
|
|
-
|
|
|
- <para>
|
|
|
- <code>isTranslated($messageId, $original = false, $locale = null)</code> takes
|
|
|
- the text you want to check as its first parameter, and as optional third parameter the locale
|
|
|
- for which you want to do the check. The optional second parameter declares whether translation
|
|
|
- is fixed to the declared language or a lower set of translations can be used. If you have a text which
|
|
|
- can be returned for 'en' but not for 'en_US' you will normally get the translation returned, but by
|
|
|
- setting <code>$original</code> to true, <code>isTranslated()</code> will return false.
|
|
|
- </para>
|
|
|
-
|
|
|
- <example id="zend.translate.using.istranslated.example">
|
|
|
- <title>Checking if a text is translatable</title>
|
|
|
- <programlisting language="php"><![CDATA[
|
|
|
-$english = array(
|
|
|
- 'message1' => 'Nachricht 1',
|
|
|
- 'message2' => 'Nachricht 2',
|
|
|
- 'message3' => 'Nachricht 3');
|
|
|
-
|
|
|
-$translate = new Zend_Translate('array', $english, 'de_AT');
|
|
|
-
|
|
|
-if ($translate->isTranslated('message1')) {
|
|
|
- print "'message1' can be translated";
|
|
|
-}
|
|
|
-
|
|
|
-if (!($translate->isTranslated('message1', true, 'de'))) {
|
|
|
- print "'message1' can not be translated to 'de'"
|
|
|
- . " as it's available only in 'de_AT'";
|
|
|
-}
|
|
|
-
|
|
|
-if ($translate->isTranslated('message1', false, 'de')) {
|
|
|
- print "'message1' can be translated in 'de_AT' as it falls back to 'de'";
|
|
|
-}
|
|
|
-]]></programlisting>
|
|
|
- </example>
|
|
|
-
|
|
|
- </sect2>
|
|
|
-
|
|
|
- <sect2 id="zend.translate.using.logging">
|
|
|
-
|
|
|
- <title>How to log not found translations</title>
|
|
|
-
|
|
|
- <para>
|
|
|
- When you have a bigger site or you are creating the translation files manually, you often have
|
|
|
- the problem that some messages are not translated. But there is an easy solution for you when you
|
|
|
- are using <classname>Zend_Translate</classname>.
|
|
|
- </para>
|
|
|
-
|
|
|
- <para>
|
|
|
- You have to follow two or three simple steps. First, you have to create an instance of
|
|
|
- <classname>Zend_Log</classname>. Then you have to attach this instance to <classname>Zend_Translate</classname>.
|
|
|
- See the following example:
|
|
|
- </para>
|
|
|
-
|
|
|
- <example id="zend.translate.using.logging.example">
|
|
|
- <title>Log translations</title>
|
|
|
- <programlisting language="php"><![CDATA[
|
|
|
-$translate = new Zend_Translate('gettext', $path, 'de');
|
|
|
-
|
|
|
-// Create a log instance
|
|
|
-$writer = new Zend_Log_Writer_Stream('/path/to/file.log');
|
|
|
-$log = new Zend_Log($writer);
|
|
|
-
|
|
|
-// Attach it to the translation instance
|
|
|
-$translate->setOptions(array(
|
|
|
- 'log' => $log,
|
|
|
- 'logUntranslated' => true));
|
|
|
-
|
|
|
-$translate->translate('unknown string');
|
|
|
-]]></programlisting>
|
|
|
- </example>
|
|
|
-
|
|
|
- <para>
|
|
|
- Now you will have a new notice in the log: <code>Untranslated message within 'de': unknown string</code>.
|
|
|
- </para>
|
|
|
-
|
|
|
- <note>
|
|
|
- <para>
|
|
|
- You should note that any translation which can not be found will be logged. This means
|
|
|
- all translations when a user requests a language which is not supported. Also every request
|
|
|
- for a message which can not be translated will be logged. Be aware, that 100 people
|
|
|
- requesting the same translation, will result 100 logged notices.
|
|
|
- </para>
|
|
|
- </note>
|
|
|
-
|
|
|
- <para>
|
|
|
- This feature can not only be used to log messages but also to attach this untranslated messages
|
|
|
- into an empty translation file. To do so you will have to write your own log writer which
|
|
|
- writes the format you want to have and strips the prepending "Untranslated message".
|
|
|
- </para>
|
|
|
-
|
|
|
- <para>
|
|
|
- You can also set the '<code>logMessage</code>' option when you want to have your own log message.
|
|
|
- Use the '<code>%message%</code>' token for placing the messageId within your log message, and the
|
|
|
- '<code>%locale%</code>' token for the requested locale. See the following example for a self
|
|
|
- defined log message:
|
|
|
- </para>
|
|
|
-
|
|
|
- <example id="zend.translate.using.logging.example2">
|
|
|
- <title>Self defined log messages</title>
|
|
|
- <programlisting language="php"><![CDATA[
|
|
|
-$translate = new Zend_Translate('gettext', $path, 'de');
|
|
|
-
|
|
|
-// Create a log instance
|
|
|
-$writer = new Zend_Log_Writer_Stream('/path/to/file.log');
|
|
|
-$log = new Zend_Log($writer);
|
|
|
-
|
|
|
-// Attach it to the translation instance
|
|
|
-$translate->setOptions(array(
|
|
|
- 'log' => $log,
|
|
|
- 'logMessage' => "Missing '%message%' within locale '%locale%'",
|
|
|
- 'logUntranslated' => true));
|
|
|
-
|
|
|
-$translate->translate('unknown string');
|
|
|
-]]></programlisting>
|
|
|
- </example>
|
|
|
-
|
|
|
- </sect2>
|
|
|
-
|
|
|
- <sect2 id="zend.translate.using.sourcedata">
|
|
|
-
|
|
|
- <title>Accessing source data</title>
|
|
|
-
|
|
|
- <para>
|
|
|
- Sometimes it is useful to have access to the translation source data. Therefor
|
|
|
- the following two functions are provided.
|
|
|
- </para>
|
|
|
-
|
|
|
- <para>
|
|
|
- The <code>getMessageIds($locale = null)</code> method returns all known message IDs as array.
|
|
|
- </para>
|
|
|
-
|
|
|
- <para>
|
|
|
- The <code>getMessages($locale = null)</code> method returns the complete translation source as
|
|
|
- an array. The message ID is used as key and the translation data as value.
|
|
|
- </para>
|
|
|
-
|
|
|
- <para>
|
|
|
- Both methods accept an optional parameter <code>$locale</code> which, if set, returns the
|
|
|
- translation data for the specified language. If this parameter is not given, the actual set
|
|
|
- language will be used. Keep in mind that normally all translations should be available in all
|
|
|
- languages. Which means that in a normal situation you will not have to set this parameter.
|
|
|
- </para>
|
|
|
-
|
|
|
- <para>
|
|
|
- Additionally the <code>getMessages()</code> method can be used to return the complete
|
|
|
- translation dictionary using the pseudo-locale 'all'. This will return all available
|
|
|
- translation data for each added locale.
|
|
|
- </para>
|
|
|
-
|
|
|
- <note>
|
|
|
- <para>
|
|
|
- Attention: the returned array can be <emphasis>very big</emphasis>,
|
|
|
- depending on the number of added locales and the amount of translation data.
|
|
|
- </para>
|
|
|
- </note>
|
|
|
-
|
|
|
- <example id="zend.translate.using.sourcedata.example">
|
|
|
- <title>Handling languages with adapters</title>
|
|
|
- <programlisting language="php"><![CDATA[
|
|
|
-// returns all known message IDs
|
|
|
-$messageIds = $translate->getMessageIds();
|
|
|
-print_r($messageIds);
|
|
|
-
|
|
|
-// or just for the specified language
|
|
|
-$messageIds = $translate->getMessageIds('en_US');
|
|
|
-print_r($messageIds);
|
|
|
-
|
|
|
-// returns all the complete translation data
|
|
|
-$source = $translate->getMessages();
|
|
|
-print_r($source);
|
|
|
-]]></programlisting>
|
|
|
- </example>
|
|
|
-
|
|
|
- </sect2>
|
|
|
-
|
|
|
</sect1>
|
|
|
<!--
|
|
|
vim:se ts=4 sw=4 et:
|
thomas