|
|
@@ -0,0 +1,317 @@
|
|
|
+<?xml version="1.0" encoding="UTF-8"?>
|
|
|
+<!-- Reviewed: no -->
|
|
|
+<sect1 id="zend.translate.sourcecreation">
|
|
|
+
|
|
|
+ <title>Creating source files</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Below you will find a description of the different source formats
|
|
|
+ which can be used with <classname>Zend_Translate</classname>.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <note>
|
|
|
+ <para>
|
|
|
+ Note that most of the described formats should be created by using
|
|
|
+ a tool or a generation process. These Tools and processes are not part
|
|
|
+ of Zend Framework and for most of the described formats free tools
|
|
|
+ are available.
|
|
|
+ </para>
|
|
|
+ </note>
|
|
|
+
|
|
|
+ <sect2 id="zend.translate.sourcecreation.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 role="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 role="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.sourcecreation.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 role="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 role="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.sourcecreation.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.sourcecreation.tmx.example">
|
|
|
+ <title>Example TMX file</title>
|
|
|
+ <programlisting role="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 role="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.sourcecreation.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.sourcecreation.csv.example">
|
|
|
+ <title>Example CSV file</title>
|
|
|
+ <programlisting language="txt"><![CDATA[
|
|
|
+#Example csv file
|
|
|
+message1;Nachricht1
|
|
|
+message2;Nachricht2
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <programlisting role="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.sourcecreation.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 role="php"><![CDATA[
|
|
|
+$translate = new Zend_Translate(
|
|
|
+ 'csv',
|
|
|
+ '/path/to/mytranslation.csv',
|
|
|
+ 'de',
|
|
|
+ array('delimiter' => ','));
|
|
|
+
|
|
|
+$translate->addTranslation('/path/to/other.csv', 'fr');
|
|
|
+]]></programlisting>
|
|
|
+ </example>
|
|
|
+
|
|
|
+ <note>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ When you are using non-ASCII characters within your CSV file, like umlauts or UTF-8
|
|
|
+ chars, then you should always use enclosure. Omitting the enclosure can lead to
|
|
|
+ missing characters in your translation.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ </note>
|
|
|
+
|
|
|
+ </sect2>
|
|
|
+
|
|
|
+ <sect2 id="zend.translate.sourcecreation.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.sourcecreation.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 role="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>{}|&~
thomas