]>
Commit | Line | Data |
---|---|---|
539d2c60 | 1 | PHP-gettext 1.0 (https://launchpad.net/php-gettext) |
659468eb | 2 | |
539d2c60 | 3 | Copyright 2003, 2006, 2009 -- Danilo "angry with PHP[1]" Segan |
659468eb AD |
4 | Licensed under GPLv2 (or any later version, see COPYING) |
5 | ||
539d2c60 | 6 | [1] PHP is actually cyrillic, and translates roughly to |
659468eb AD |
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 | |
539d2c60 AD |
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. | |
659468eb | 58 | |
659468eb | 59 | |
539d2c60 | 60 | Bugs |
659468eb | 61 | |
539d2c60 | 62 | Report them on https://bugs.launchpad.net/php-gettext |
659468eb AD |
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 | ||
539d2c60 AD |
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 | |
659468eb AD |
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 | |
539d2c60 | 84 | disposal, so may run: |
659468eb AD |
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 | |
539d2c60 | 89 | extract all the strings. In above example, try with |
659468eb AD |
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 | ||
539d2c60 AD |
101 | Check example in examples/pig_dropin.php, basically you include |
102 | gettext.inc and use all the standard gettext interfaces as | |
659468eb AD |
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 | ||
539d2c60 | 120 | TODO: |
659468eb | 121 | |
539d2c60 AD |
122 | o Improve speed to be even more comparable to the native gettext |
123 | implementation. | |
659468eb | 124 | |
539d2c60 | 125 | o Try to use hash tables in MO files: with pre-loading, would it |
659468eb AD |
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 | |
539d2c60 | 135 | indicate that there's zero improvement and/or change compared to |
659468eb AD |
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...? | |
539d2c60 | 148 | |
659468eb AD |
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. |