]> projects.mako.cc - scuttle/blob - includes/php-gettext/README
- Allow blacklisting and whitelisting of e-mail addresses used for new user accounts
[scuttle] / includes / php-gettext / README
1 PHP-gettext 1.0 (https://launchpad.net/php-gettext)
2
3 Copyright 2003, 2006, 2009 -- Danilo "angry with PHP[1]" Segan
4 Licensed under GPLv2 (or any later version, see COPYING)
5
6 [1] PHP is actually cyrillic, and translates roughly to
7     "works-doesn't-work" (UTF-8: Ради-Не-Ради)
8
9
10 Introduction
11
12     How many times did you look for a good translation tool, and
13     found out that gettext is best for the job? Many times.
14
15     How many times did you try to use gettext in PHP, but failed
16     miserably, because either your hosting provider didn't support
17     it, or the server didn't have adequate locale? Many times.
18
19     Well, this is a solution to your needs. It allows using gettext
20     tools for managing translations, yet it doesn't require gettext
21     library at all. It parses generated MO files directly, and thus
22     might be a bit slower than the (maybe provided) gettext library.
23
24     PHP-gettext is a simple reader for GNU gettext MO files. Those
25     are binary containers for translations, produced by GNU msgfmt.
26
27 Why?
28
29     I got used to having gettext work even without gettext
30     library. It's there in my favourite language Python, so I was
31     surprised that I couldn't find it in PHP. I even Googled for it,
32     but to no avail.
33
34     So, I said, what the heck, I'm going to write it for this
35     disguisting language of PHP, because I'm often constrained to it.
36
37 Features
38
39   o Support for simple translations
40     Just define a simple alias for translate() function (suggested
41     use of _() or gettext(); see provided example).
42
43   o Support for ngettext calls (plural forms, see a note under bugs)
44     You may also use plural forms. Translations in MO files need to
45     provide this, and they must also provide "plural-forms" header.
46     Please see 'info gettext' for more details.
47
48   o Support for reading straight files, or strings (!!!)
49     Since I can imagine many different backends for reading in the MO
50     file data, I used imaginary abstract class StreamReader to do all
51     the input (check streams.php). For your convenience, I've already
52     provided two classes for reading files: FileReader and
53     StringReader (CachedFileReader is a combination of the two: it
54     loads entire file contents into a string, and then works on that).
55     See example below for usage. You can for instance use StringReader
56     when you read in data from a database, or you can create your own
57     derivative of StreamReader for anything you like.
58
59
60 Bugs
61
62     Report them on https://bugs.launchpad.net/php-gettext
63
64 Usage
65
66     Put files streams.php and gettext.php somewhere you can load them
67     from, and require 'em in where you want to use them.
68
69     Then, create one 'stream reader' (a class that provides functions
70     like read(), seekto(), currentpos() and length()) which will
71     provide data for the 'gettext_reader', with eg.
72       $streamer = new FileStream('data.mo');
73
74     Then, use that as a parameter to gettext_reader constructor:
75       $wohoo = new gettext_reader($streamer);
76
77     If you want to disable pre-loading of entire message catalog in
78     memory (if, for example, you have a multi-thousand message catalog
79     which you'll use only occasionally), use "false" for second
80     parameter to gettext_reader constructor:
81       $wohoo = new gettext_reader($streamer, false);
82
83     From now on, you have all the benefits of gettext data at your
84     disposal, so may run:
85       print $wohoo->translate("This is a test");
86       print $wohoo->ngettext("%d bird", "%d birds", $birds);
87
88     You might need to pass parameter "-k" to xgettext to make it
89     extract all the strings. In above example, try with
90       xgettext -ktranslate -kngettext:1,2 file.php
91     what should create messages.po which contains two messages for
92     translation.
93
94     I suggest creating simple aliases for these functions (see
95     example/pigs.php for how do I do it, which means it's probably a
96     bad way).
97
98
99 Usage with gettext.inc (standard gettext interfaces emulation)
100
101     Check example in examples/pig_dropin.php, basically you include
102     gettext.inc and use all the standard gettext interfaces as
103     documented on:
104
105        http://www.php.net/gettext
106
107     The only catch is that you can check return value of setlocale()
108     to see if your locale is system supported or not.
109
110
111 Example
112
113     See in examples/ subdirectory. There are a couple of files.
114     pigs.php is an example, serbian.po is a translation to Serbian
115     language, and serbian.mo is generated with
116        msgfmt -o serbian.mo serbian.po
117     There is also simple "update" script that can be used to generate
118     POT file and to update the translation using msgmerge.
119
120 TODO:
121
122   o Improve speed to be even more comparable to the native gettext
123     implementation.
124
125   o Try to use hash tables in MO files: with pre-loading, would it
126     be useful at all?
127
128 Never-asked-questions:
129
130   o Why did you mark this as version 1.0 when this is the first code
131     release?
132
133     Well, it's quite simple. I consider that the first released thing
134     should be labeled "version 1" (first, right?). Zero is there to
135     indicate that there's zero improvement and/or change compared to
136     "version 1".
137
138     I plan to use version numbers 1.0.* for small bugfixes, and to
139     release 1.1 as "first stable release of version 1".
140
141     This may trick someone that this is actually useful software, but
142     as with any other free software, I take NO RESPONSIBILITY for
143     creating such a masterpiece that will smoke crack, trash your
144     hard disk, and make lasers in your CD device dance to the tune of
145     Mozart's 40th Symphony (there is one like that, right?).
146
147   o Can I...?
148
149     Yes, you can. This is free software (as in freedom, free speech),
150     and you might do whatever you wish with it, provided you do not
151     limit freedom of others (GPL).
152
153     I'm considering licensing this under LGPL, but I *do* want
154     *every* PHP-gettext user to contribute and respect ideas of free
155     software, so don't count on it happening anytime soon.
156
157     I'm sorry that I'm taking away your freedom of taking others'
158     freedom away, but I believe that's neglible as compared to what
159     freedoms you could take away. ;-)
160
161     Uhm, whatever.

Benjamin Mako Hill || Want to submit a patch?