XLI. Gettext

Wstęp

The gettext functions implement an NLS (Native Language Support) API which can be used to internationalize your PHP applications. Please see the gettext documentation for your system for a thorough explanation of these functions or view the docs at http://www.gnu.org/software/gettext/manual/gettext.html.

Wymagania

To use these functions you must download and install the GNU gettext package from http://www.gnu.org/software/gettext/gettext.html

Instalacja

To include GNU gettext support in your PHP build you must add the option --with-gettext[=DIR] where DIR is the gettext install directory, defaults to /usr/local.

Konfiguracja czasu wykonywania

To rozszerzenie nie definiuje posiada żadnych dyrektyw konfiguracyjnych w pliku php.ini.

Typy zasobów

To rozszerzenie nie posiada żadnych rodzajów zasobów.

Stałe predefinopwane

To rozszerzenie nie posiada żadnych stałych.

Spis treści
bind_textdomain_codeset -- Specify the character encoding in which the messages from the DOMAIN message catalog will be returned
bindtextdomain -- Sets the path for a domain
dcgettext -- Overrides the domain for a single lookup
dcngettext -- Plural version of dcgettext
dgettext -- Override the current domain
dngettext -- Plural version of dgettext
gettext -- Lookup a message in the current domain
ngettext -- Plural version of gettext
textdomain -- Sets the default domain

User Contributed Notes


if you're having trouble with setlocale (if it's returning false) on ubuntu or debian:



nano /etc/locale.gen



make sure that the locales taht you want are in the list, if not, add them. for instance, i wanted es_GT (b/c i have an app that must run on redhat and debian, i cant change to es_GT.UTF-8) so, add:



es_GT UTF-8



then run:



locale-gen 



you now have the locales you want, not just the ones the system magically came with


There exists an emulation for the gettext functions - obviously slower than the native binding, but can be used on shared servers which lack the extension. It is believed to be rather useful as fallback (comes already encapsulated with if-function_exists checks).

See the ext/ directory in the [ http://freshmeat.net/p/upgradephp ] tarball.  Support for plural translations isn't there, because that is too hard to get reimplemented reliably.


Make sure you check your webserver configuration before deciding to use gettext, because if you are running in a multi-threaded environment you should not use gettext, as it is not thread-safe.



A future version of gettext(possibly 0.15) may be thread-safe.

Any gettext dependencies, such as glibc would also need to be thread-safe.



Apache 1.3 on Unix generally is non-threaded, but on Windows it is multithreaded.

Apache 2.0 has support for MPMs(Multi-Processing Modules), some of which support multiple threads:

http://httpd.apache.org/docs-2.0/mpm.html


If gettext does not work with your locale, ie 'zh_CN', just going to see if the output of command "localedef --list-archive" contains your locale('zh_CN' in this example).

If it not, try to use a exist locale or use "localedef" to create one: "localedef -f GBK -i zh_CN zh_CN" in my case.


winXP, PHP 4.3.5 as Apache1.3.29 module



Two hints for Windows users.



I found setting locale is neither sufficient nor nessecery. To get it work I needed to set either LC_ALL or LANG enviroment variable to my locale. Anyway this value must be proper for setlocale so it is good to test with it. In my case it was bgr_BGR for bulgarian according to http://www.unicode.org/onlinedat/countries.html



gettext checks for files once and keeps them in cashe. Especially it means that if it doesn't find your files it won't search again, so restart Apache after any directory changes!! 



My minimal working script:

<?php

// translation file: D:\Apache\htdocs\mypage\locale\bgr_BGR\LC_MESSAGES\messages.mo

putenv("LC_ALL=bgr_BGR");

bindtextdomain('messages', 'D:\Apache\htdocs\mypage\locale\\');

echo gettext("Hello");

?>


Reading the line



<? php setlocale(LC_ALL, 'de_DE'); ?>



here over and over again, I have to warn using it, as there are severe caveats. For certain locales, LC_NUMERIC swaps period and comma, which may e.g. lead to decimals silently stripped of numbers, when inserting rows into an SQL database. So DON'T do this, but use



<? php setlocale(LC_MESSAGES, 'de_DE'); ?>



instead, which does exactly what you want, without any nasty side effecs.


Following three lines take about 0.5 second to execute (Debian, Celeron 2GHz, 256MB RAM):



setlocale(LC_ALL, 'pl_PL'); 

bindtextdomain('my_domain', '../dir/' . 'locale'); 

textdomain('my_domain'); 



I think that such delay is important enough to be mentioned in the documentation. In my particular case, it means more than doubled execution time for the entire script.


Check your 



/etc/locales.aliases for "english en_GB.ISO-8859-1" (mentioned before) 



and your



/etc/locales.gen for en_GB.ISO-8859-15 ISO-8859-15 



I'm not sure if only this entry solved the problem. In my case this entry was made by an dpkg-reconfigure locales (debian), where i created the locales.



Translation only works with de_GE@euro and  en_GB.ISO-8859-15 (first column in you locales.gen)


Of course, translation is only interesting if you provide the user with the language and encoding he asks for. Since there's part of the HTTP protocol that allows you to specify that, it's nice if one can use that information to pick the 'right' translation out of the ones you have available.



I wrote something that does just that -- it parses the 'Accept-Language' and 'Accept-Charset' HTTP/1.1 headers, and tells you which one the user prefers out of a list you provide. You can download it at http://www.grep.be/articles/php-accept.php



Note that even if the user's browser may support this, the user may not know about it; as such, it's probably good practice not to remove links to other-languaged versions, so that people can still get a version of your site in another language if they so prefer.


I had a lot of problems getting gettext to work (RedHat 7.3). After reading ALL the comments in this manual, I got it to work OK.



In summary, take care that:



1) You use a full locale in the setlocale()

2) Your language_country exists in the /usr/share/locale/locale.alias

3) It seems that Apache needs to be restarted (a "graceful" did the trick for me)

4) Your .mo files must be named after the domain



My code:



$language = "es_ES";

$locale = setlocale(LC_ALL, $language);



$gettext_domain = 'messages';

bindtextdomain($gettext_domain, "/full/path/to/locale");

textdomain($gettext_domain);


Even though in some cases setlocale() may require a country code in addition to the language code this does not mean that it is required for gettext. 



If setlocale() is set to either es_ES or es_MX gettext() will still get the text from a po file in the 'es' folder.



It probably is not a good idea to go changing a systems alias file(s) just to avoid the verbosity of the ISO standard because:

  a) you might break something 

  b) your code just lost it's portability



.


The way I got gettext to work with just a standard "de" or "fr" instead of "de_DE" was I overwrote my /usr/share/locale/locale.alias with /usr/lib/X11/locale/locale.alias file.  The I restarted Apache.  Reason I did this was it appeared the X11 file was more up to date and more modernised!


Sorry, one more info :



the previous post is especially interesting when you have values set on the server for some of the LC_... then, setlocale() output gives you all the LC_... with their value.



BUT do not forget that the priority order for gettext is:



LANGUAGE

LC_ALL

LC_MESSAGES

LANG



Then, if ever you script always translate to the same language, check the value of LANGUAGE ...


One trick I found after HOURS of tries :



when you use the setlocale(), PHP will use the locale info it will find in, for example, /usr/share/locale to set the language info for LC_ALL, LC_MESSAGES, ...



You can check the exact info it will use by using putenv() with LANG=.... and looking at the return value of setlocale(LC_ALL, ""). The language value your gettext function will use to look for your translation file is the one given for LC_MESSAGES.



Example :



I was setting the LANG as fr_BE, and placed the translation file in dirxxx/locale/fr_BE/LC_MESSAGES/...

As it was locale info in my system for fr_BE but NOT LC_MESSAGES, PHP choosed to use the LC_MESSAGES settings for fr_FR instead and then, was looking for a translation file in dirxxx/locale/fr_FR/LC_MESSAGES/..., which wasn't found of course.



So, just make sure to look at the return value of setlocale to see what language value is associated to LC_MESSAGES and, then, to know in which subdirectory the translation file will be looked for by gettext.



Robert


Some tips from my Red Hat Linux 7.3 system.



It didn't work for me until I set a full locale (i.e. es_ES) with setlocale.



I was trying with Michele Manzato's example (thank you!), but as it sets the language without the country, it was failing for me. Here is the example "fixed" with full locale:



// Change to script directory

// (Not needed in RH 7.3)

$path = dirname(getenv(PATH_TRANSLATED));

chdir($path);



// Set the language as full locale 'es_ES'

$language = 'es_ES';

putenv("LANG=$language");

setlocale(LC_ALL, $language);



// Set the text domain as 'mydomain'

$domain = 'mydomain';

bindtextdomain("$domain", "./locale");

textdomain("$domain");



// The .mo file searched is:

// ./locale/es_ES/LC_MESSAGES/mydomain.mo

// or if previous one doesn't exist:

// ./locale/es/LC_MESSAGES/mydomain.mo



echo gettext("Hello world!"); 



Hope this helps!

Eneko.


Corrections to "hace_x at yahoo dot com" message.



Note : The backslash have been removed in the greetings.po sample code (before the n characters at end of lines).



Same thing for ".includestranslations" to move into "./includes/translations" in php sample.



I used mingw (http://www.mingw.org) with gettext package (http://sourceforge.net/projects/mingwrep) to make it work under WinXp.



I uncoment also "extension=php_gettext.dll" in php.ini (I am using easy php 1.6.0.0)



Here is my conv.bat to generate french translation :



set path=c:\mingw\bin

msgfmt -v -o greetings.mo greetings.po 

pause



That's all !



Yann Le Doar