| blob | 3d4fa21f5c1cb14f79d1d25798182b6b8074d6e2 |
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!-- Reviewed: no -->
3 <sect1 id="zend.translate.adapter">
4 <title>Adapters for Zend_Translate</title>
6 <para>
7 <classname>Zend_Translate</classname> can handle different adapters for translation.
8 Each adapter has its own advantages and disadvantages.
9 Below is a comprehensive list of all supported adapters for
10 translation source files.
11 </para>
13 <table id="zend.translate.adapter.table">
14 <title>Adapters for Zend_Translate</title>
16 <tgroup cols="3">
17 <thead>
18 <row>
19 <entry>Adapter</entry>
20 <entry>Description</entry>
21 <entry>Usage</entry>
22 </row>
23 </thead>
25 <tbody>
26 <row>
27 <entry>Array</entry>
28 <entry>Use <acronym>PHP</acronym> arrays</entry>
29 <entry>Small pages; simplest usage; only for programmers</entry>
30 </row>
32 <row>
33 <entry>Csv</entry>
34 <entry>Use comma separated (*.csv/*.txt) files</entry>
36 <entry>
37 Simple text file format; fast; possible problems with unicode characters
38 </entry>
39 </row>
41 <row>
42 <entry>Gettext</entry>
43 <entry>Use binary gettext (*.mo) files</entry>
44 <entry>GNU standard for linux; thread-safe; needs tools for translation</entry>
45 </row>
47 <row>
48 <entry>Ini</entry>
49 <entry>Use simple <acronym>INI</acronym> (*.ini) files</entry>
51 <entry>
52 Simple text file format; fast; possible problems with unicode characters
53 </entry>
54 </row>
56 <row>
57 <entry>Tbx</entry>
58 <entry>Use termbase exchange (*.tbx/*.xml) files</entry>
60 <entry>
61 Industry standard for inter application terminology strings;
62 <acronym>XML</acronym> format
63 </entry>
64 </row>
66 <row>
67 <entry>Tmx</entry>
68 <entry>Use tmx (*.tmx/*.xml) files</entry>
70 <entry>
71 Industry standard for inter application translation; <acronym>XML</acronym>
72 format; human readable
73 </entry>
74 </row>
76 <row>
77 <entry>Qt</entry>
78 <entry>Use qt linguist (*.ts) files</entry>
80 <entry>
81 Cross platform application framework; <acronym>XML</acronym> format; human
82 readable
83 </entry>
84 </row>
86 <row>
87 <entry>Xliff</entry>
88 <entry>Use xliff (*.xliff/*.xml) files</entry>
90 <entry>
91 A simpler format as <constant>TMX</constant> but related to it;
92 <acronym>XML</acronym> format; human readable
93 </entry>
94 </row>
96 <row>
97 <entry>XmlTm</entry>
98 <entry>Use xmltm (*.xml) files</entry>
100 <entry>
101 Industry standard for <acronym>XML</acronym> document translation memory;
102 <acronym>XML</acronym> format; human readable
103 </entry>
104 </row>
106 <row>
107 <entry>Others</entry>
108 <entry>*.sql</entry>
109 <entry>Different other adapters may be implemented in the future</entry>
110 </row>
111 </tbody>
112 </tgroup>
113 </table>
115 <sect2 id="zend.translate.adapter.decision">
116 <title>How to decide which translation adapter to use</title>
118 <para>
119 You should decide which Adapter you want to use for
120 <classname>Zend_Translate</classname>. Frequently, external criteria such as a project
121 requirement or a customer requirement determines this for you, but if you are in
122 the position to do this yourself, the following hints may simplify
123 your decision.
124 </para>
126 <note>
127 <para>
128 When deciding your adapter you should also be aware of the used
129 encoding. Even if Zend Framework declares UTF-8 as default
130 encoding you will sometimes be in the need of other encoding.
131 <classname>Zend_Translate</classname> will not change any encoding which is defined
132 within the source file which means that if your Gettext source
133 is build upon ISO-8859-1 it will also return strings in this encoding
134 without converting them. There is only one restriction:
135 </para>
137 <para>
138 When you use a <acronym>XML</acronym> based source format like TMX or XLIFF you must
139 define the encoding within the <acronym>XML</acronym> files header because
140 <acronym>XML</acronym> files without defined encoding will be treated as UTF-8 by
141 any <acronym>XML</acronym> parser by default. You should also be aware that actually
142 the encoding of <acronym>XML</acronym> files is limited to the encodings supported
143 by <acronym>PHP</acronym> which are UTF-8, ISO-8859-1 and US-ASCII.
144 </para>
145 </note>
147 <sect3 id="zend.translate.adapter.array">
148 <title>Zend_Translate_Adapter_Array</title>
150 <para>
151 The Array Adapter is the Adapter which is simplest to use for
152 programmers.
153 But when you have numerous translation strings or many
154 languages you should think about another Adapter.
155 For example, if you have 5000 translation strings,
156 the Array Adapter is possibly not the best choice for you.
157 </para>
159 <para>
160 You should only use this Adapter for small sites with a handful
161 of languages, and if you or your programmer team creates the
162 translations yourselves.
163 </para>
164 </sect3>
166 <sect3 id="zend.translate.adapter.csv">
167 <title>Zend_Translate_Adapter_Csv</title>
169 <para>
170 The Csv Adapter is the Adapter which is simplest to use for
171 customers.
172 CSV files are readable by standard text editors, but
173 text editors often do not support utf8 character sets.
174 </para>
176 <para>
177 You should only use this Adapter if your customer wants to do
178 translations himself.
179 </para>
181 <note>
182 <para>
183 Beware that the Csv Adapter has problems when your Csv files are encoded
184 differently than the locale setting of your environment. This is due to a Bug of
185 <acronym>PHP</acronym> itself which will not be fixed before
186 <acronym>PHP</acronym> 6.0 (http://bugs.php.net/bug.php?id=38471). So you should
187 be aware that the Csv Adapter due to <acronym>PHP</acronym> restrictions is not
188 locale aware.
189 </para>
190 </note>
191 </sect3>
193 <sect3 id="zend.translate.adapter.gettext">
194 <title>Zend_Translate_Adapter_Gettext</title>
196 <para>
197 The Gettext Adapter is the Adapter which is used most
198 frequently. Gettext is a translation source format which was
199 introduced by GNU, and is now used worldwide.
200 It is not human readable, but there are several freeware tools
201 (for instance, <ulink url="http://sourceforge.net/projects/poedit/">POEdit</ulink>),
202 which are very helpful. The <classname>Zend_Translate</classname> Gettext Adapter is
203 not implemented using <acronym>PHP</acronym>'s gettext extension.
204 You can use the Gettext Adapter even if you do not have
205 the <acronym>PHP</acronym> gettext extension installed.
206 Also the Adapter is thread-safe and the <acronym>PHP</acronym> gettext extension
207 is currently not thread-safe.
208 </para>
210 <para>
211 Most people will use this adapter.
212 With the available tools, professional translation is
213 very simple. But gettext data are is stored in a
214 machine-readable format, which is not readable without tools.
215 </para>
216 </sect3>
218 <sect3 id="zend.translate.adapter.ini">
219 <title>Zend_Translate_Adapter_Ini</title>
221 <para>
222 The Ini Adapter is a very simple Adapter which can even be used
223 directly by customers.
224 <acronym>INI</acronym> files are readable by standard text editors, but
225 text editors often do not support utf8 character sets.
226 </para>
228 <para>
229 You should only use this Adapter when your customer wants to do translations
230 himself. Do not use this adapter as generic translation source.
231 </para>
233 <warning>
234 <title>Regression in PHP 5.3</title>
236 <para>
237 Prior to <acronym>PHP</acronym> 5.3, <methodname>parse_ini_file()</methodname>
238 and <methodname>parse_ini_string()</methodname> handled non-ASCII characters
239 within <acronym>INI</acronym> option keys worked without an issue. However,
240 starting with <acronym>PHP</acronym> 5.3, any such keys will now be silently
241 dropped in the returned array from either function. If you had keys utilizing
242 UTF-8 or Latin-1 characters, you may find your translations no longer work when
243 using the <acronym>INI</acronym> adapter. If this is the case, we recommend
244 utilizing a different adapter.
245 </para>
246 </warning>
247 </sect3>
249 <sect3 id="zend.translate.adapter.tbx">
250 <title>Zend_Translate_Adapter_Tbx</title>
252 <para>
253 The Tbx Adapter is an Adapter which will be used by customers
254 which already use the TBX format for their internal translation
255 system. Tbx is no standard translation format but more a collection
256 of already translated and pre translated source strings. When you
257 use this adapter you have to be sure that all your needed source
258 string are translated.
259 TBX is a <acronym>XML</acronym> file based format and a completely new format.
260 <acronym>XML</acronym> files are human-readable, but the parsing is not as fast
261 as with gettext files.
262 </para>
264 <para>
265 This adapter is perfect for companies when pre translated
266 source files already exist.
267 The files are human readable and system-independent.
268 </para>
269 </sect3>
271 <sect3 id="zend.translate.adapter.tmx">
272 <title>Zend_Translate_Adapter_Tmx</title>
274 <para>
275 The Tmx Adapter is the Adapter which will be used by most
276 customers which have multiple systems which use the same
277 translation source, or when the translation source must be
278 system-independent.
279 TMX is a <acronym>XML</acronym> file based format, which is announced to be the
280 next industry standard.
281 <acronym>XML</acronym> files are human-readable, but the parsing is not as fast
282 as with gettext files.
283 </para>
285 <para>
286 Most medium to large companies use this adapter.
287 The files are human readable and system-independent.
288 </para>
289 </sect3>
291 <sect3 id="zend.translate.adapter.qt">
292 <title>Zend_Translate_Adapter_Qt</title>
294 <para>
295 The Qt Adapter is for all customers which have TS files as their
296 translation source which are made by QtLinguist.
297 QT is a <acronym>XML</acronym> file based format.
298 <acronym>XML</acronym> files are human-readable, but the parsing is not as fast
299 as with gettext files.
300 </para>
302 <para>
303 Several big players have build software upon the QT framework.
304 The files are human readable and system-independent.
305 </para>
306 </sect3>
308 <sect3 id="zend.translate.adapter.xliff">
309 <title>Zend_Translate_Adapter_Xliff</title>
311 <para>
312 The Xliff Adapter is the Adapter which will be used by most customers which
313 want to have <acronym>XML</acronym> files but do not have tools for TMX.
314 XLIFF is a <acronym>XML</acronym> file based format, which is related to TMX but
315 simpler as it does not support all possibilities of it.
316 <acronym>XML</acronym> files are human-readable, but the parsing is not as fast
317 as with gettext files.
318 </para>
320 <para>
321 Most medium companies use this adapter.
322 The files are human readable and system-independent.
323 </para>
324 </sect3>
326 <sect3 id="zend.translate.adapter.xmltm">
327 <title>Zend_Translate_Adapter_XmlTm</title>
329 <para>
330 The XmlTm Adapter is the Adapter which will be used by customers
331 which do their layout themself. XmlTm is a format which allows the
332 complete <acronym>HTML</acronym> source to be included in the translation source, so
333 the translation is coupled with the layout.
334 XLIFF is a <acronym>XML</acronym> file based format, which is related to XLIFF but
335 its not as simple to read.
336 </para>
338 <para>
339 This adapter should only be used when source files already exist.
340 The files are human readable and system-independent.
341 </para>
342 </sect3>
343 </sect2>
345 <sect2 id="zend.translate.adapter.selfwritten">
346 <title>Integrate self written Adapters</title>
348 <para>
349 <classname>Zend_Translate</classname> allows you to integrate and use self written
350 Adapter classes. They can be used like the standard Adapter classes which
351 are already included within <classname>Zend_Translate</classname>.
352 </para>
354 <para>
355 Any adapter class you want to use with <classname>Zend_Translate</classname> must be a
356 subclass of <classname>Zend_Translate_Adapter</classname>.
357 <classname>Zend_Translate_Adapter</classname> is an abstract class which already defines
358 all what is needed for translation. What has to be done by you, is the definition of the
359 reader for translation datas.
360 </para>
362 <para>
363 The usage of the prefix "Zend" should be limited to Zend Framework.
364 If you extend <classname>Zend_Translate</classname> with your own adapter, you should
365 name it like "Company_Translate_Adapter_MyFormat". The following code shows an
366 example of how a self written adapter class could be implemented:
367 </para>
369 <programlisting language="php"><![CDATA[
370 try {
371 $translate = new Zend_Translate(
372 array(
373 'adapter' => 'Company_Translate_Adapter_MyFormat',
374 'content' => '/path/to/translate.xx',
375 'locale' => 'en',
376 'myoption' => 'myvalue'
377 )
378 );
379 } catch (Exception $e) {
380 // File not found, no adapter class...
381 // General failure
382 }
383 ]]></programlisting>
384 </sect2>
386 <sect2 id="zend.translate.adapter.caching">
387 <title>Speedup all Adapters</title>
389 <para>
390 <classname>Zend_Translate</classname> allows you use internally
391 <classname>Zend_Cache</classname> to fasten the loading of translation sources. This
392 comes very handy if you use many translation sources or extensive source formats like
393 <acronym>XML</acronym> based files.
394 </para>
396 <para>
397 To use caching you will just have to give a cache object to the
398 <methodname>Zend_Translate::setCache()</methodname> method. It takes a instance of
399 <classname>Zend_Cache</classname> as only parameter. Also if you use any adapter direct
400 you can use the <methodname>setCache()</methodname> method. For convenience there are
401 also the static methods <methodname>getCache()</methodname>,
402 <methodname>hasCache()</methodname>, <methodname>clearCache()</methodname> and
403 <methodname>removeCache()</methodname>.
404 </para>
406 <programlisting language="php"><![CDATA[
407 $cache = Zend_Cache::factory('Core',
408 'File',
409 $frontendOptions,
410 $backendOptions);
411 Zend_Translate::setCache($cache);
412 $translate = new Zend_Translate(
413 array(
414 'adapter' => 'gettext',
415 'content' => '/path/to/translate.mo',
416 'locale' => 'en'
417 )
418 );
419 ]]></programlisting>
421 <note>
422 <para>
423 You must set the cache <emphasis>before</emphasis> you use or initiate
424 any adapter or instance of <classname>Zend_Translate</classname>. Otherwise your
425 translation source will not be cached until you add a new source with the
426 <methodname>addTranslation()</methodname> method.
427 </para>
428 </note>
429 </sect2>
430 </sect1>
431 <!--
432 vim:se ts=4 sw=4 et:
433 -->