summaryrefslogtreecommitdiff
path: root/includes/php-gettext/README
diff options
context:
space:
mode:
Diffstat (limited to 'includes/php-gettext/README')
-rw-r--r--includes/php-gettext/README189
1 files changed, 0 insertions, 189 deletions
diff --git a/includes/php-gettext/README b/includes/php-gettext/README
deleted file mode 100644
index c7525e2..0000000
--- a/includes/php-gettext/README
+++ /dev/null
@@ -1,189 +0,0 @@
-PHP-gettext 1.0
-
-Copyright 2003, 2006 -- Danilo "angry with PHP[1]" Segan
-Licensed under GPLv2 (or any later version, see COPYING)
-
-[1] PHP is actually cyrillic, and translates roughly to
- "works-doesn't-work" (UTF-8: Ради-Не-Ради)
-
-
-Introduction
-
- How many times did you look for a good translation tool, and
- found out that gettext is best for the job? Many times.
-
- How many times did you try to use gettext in PHP, but failed
- miserably, because either your hosting provider didn't support
- it, or the server didn't have adequate locale? Many times.
-
- Well, this is a solution to your needs. It allows using gettext
- tools for managing translations, yet it doesn't require gettext
- library at all. It parses generated MO files directly, and thus
- might be a bit slower than the (maybe provided) gettext library.
-
- PHP-gettext is a simple reader for GNU gettext MO files. Those
- are binary containers for translations, produced by GNU msgfmt.
-
-Why?
-
- I got used to having gettext work even without gettext
- library. It's there in my favourite language Python, so I was
- surprised that I couldn't find it in PHP. I even Googled for it,
- but to no avail.
-
- So, I said, what the heck, I'm going to write it for this
- disguisting language of PHP, because I'm often constrained to it.
-
-Features
-
- o Support for simple translations
- Just define a simple alias for translate() function (suggested
- use of _() or gettext(); see provided example).
-
- o Support for ngettext calls (plural forms, see a note under bugs)
- You may also use plural forms. Translations in MO files need to
- provide this, and they must also provide "plural-forms" header.
- Please see 'info gettext' for more details.
-
- o Support for reading straight files, or strings (!!!)
- Since I can imagine many different backends for reading in the MO
- file data, I used imaginary abstract class StreamReader to do all
- the input (check streams.php). For your convenience, I've already
- provided two classes for reading files: FileReader and
- StringReader (CachedFileReader is a combination of the two: it
- loads entire file contents into a string, and then works on that).
- See example below for usage. You can for instance use StringReader
- when you read in data from a database, or you can create your own
- derivative of StreamReader for anything you like.
-
-
-Bugs
-
- Plural-forms field in MO header (translation for empty string,
- i.e. "") is treated according to PHP syntactic rules (it's
- eval()ed). Since these should actually follow C syntax, there are
- some problems.
-
- For instance, I'm used to using this:
- Plural-Forms: nplurals=3; plural=n%10==1 && n%100!=11 ? 0 : \
- n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;
- but it fails with PHP (it sets $plural=2 instead of 0 for $n==1).
-
- The fix is usually simple, but I'm lazy to go into the details of
- PHP operator precedence, and maybe try to fix it. In here, I had
- to put everything after the first ':' in parenthesis:
- Plural-Forms: nplurals=3; plural=n%10==1 && n%100!=11 ? 0 : \
- (n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2);
- That works, and I'm satisfied.
-
- Besides this one, there are probably a bunch of other bugs, since
- I hate PHP (did I mention it already? no? strange), and don't
- know it very well. So, feel free to fix any of those and report
- them back to me at <danilo@kvota.net>.
-
-Usage
-
- Put files streams.php and gettext.php somewhere you can load them
- from, and require 'em in where you want to use them.
-
- Then, create one 'stream reader' (a class that provides functions
- like read(), seekto(), currentpos() and length()) which will
- provide data for the 'gettext_reader', with eg.
- $streamer = new FileStream('data.mo');
-
- Then, use that as a parameter to gettext_reader constructor:
- $wohoo = new gettext_reader($streamer);
-
- If you want to disable pre-loading of entire message catalog in
- memory (if, for example, you have a multi-thousand message catalog
- which you'll use only occasionally), use "false" for second
- parameter to gettext_reader constructor:
- $wohoo = new gettext_reader($streamer, false);
-
- From now on, you have all the benefits of gettext data at your
- disposal, so may run:
- print $wohoo->translate("This is a test");
- print $wohoo->ngettext("%d bird", "%d birds", $birds);
-
- You might need to pass parameter "-k" to xgettext to make it
- extract all the strings. In above example, try with
- xgettext -ktranslate -kngettext:1,2 file.php
- what should create messages.po which contains two messages for
- translation.
-
- I suggest creating simple aliases for these functions (see
- example/pigs.php for how do I do it, which means it's probably a
- bad way).
-
-
-Usage with gettext.inc (standard gettext interfaces emulation)
-
- Check example in examples/pig_dropin.php, basically you include
- gettext.inc and use all the standard gettext interfaces as
- documented on:
-
- http://www.php.net/gettext
-
- The only catch is that you can check return value of setlocale()
- to see if your locale is system supported or not.
-
-
-Example
-
- See in examples/ subdirectory. There are a couple of files.
- pigs.php is an example, serbian.po is a translation to Serbian
- language, and serbian.mo is generated with
- msgfmt -o serbian.mo serbian.po
- There is also simple "update" script that can be used to generate
- POT file and to update the translation using msgmerge.
-
-Interesting TODO:
-
- o Try to parse "plural-forms" header field, and to follow C syntax
- rules. This won't be easy.
-
-Boring TODO:
-
- o Learn PHP and fix bugs, slowness and other stuff resulting from
- my lack of knowledge (but *maybe*, it's not my knowledge that is
- bad, but PHP itself ;-).
-
- (This is mostly done thanks to Nico Kaiser.)
-
- o Try to use hash tables in MO files: with pre-loading, would it
- be useful at all?
-
-Never-asked-questions:
-
- o Why did you mark this as version 1.0 when this is the first code
- release?
-
- Well, it's quite simple. I consider that the first released thing
- should be labeled "version 1" (first, right?). Zero is there to
- indicate that there's zero improvement and/or change compared to
- "version 1".
-
- I plan to use version numbers 1.0.* for small bugfixes, and to
- release 1.1 as "first stable release of version 1".
-
- This may trick someone that this is actually useful software, but
- as with any other free software, I take NO RESPONSIBILITY for
- creating such a masterpiece that will smoke crack, trash your
- hard disk, and make lasers in your CD device dance to the tune of
- Mozart's 40th Symphony (there is one like that, right?).
-
- o Can I...?
-
- Yes, you can. This is free software (as in freedom, free speech),
- and you might do whatever you wish with it, provided you do not
- limit freedom of others (GPL).
-
- I'm considering licensing this under LGPL, but I *do* want
- *every* PHP-gettext user to contribute and respect ideas of free
- software, so don't count on it happening anytime soon.
-
- I'm sorry that I'm taking away your freedom of taking others'
- freedom away, but I believe that's neglible as compared to what
- freedoms you could take away. ;-)
-
- Uhm, whatever.