The Server Pages
:: TSP Menu
- Home
- Authors
- Glossary
- RSS Feed

:: Servers
- CPanel
- Hosting
- Linux
- Windows

:: Webmaster
- Databases
- Design
- Search Engines

:: Scripts
- Scripts

:: Documentation
- PHP Manual

:: Other
- Errors & Solutions
- TechPunt
- Wojjie

search for in the

bind_textdomain_codeset> <Predefined Constants
[edit] Last updated: Sat, 12 May 2012

view this page in

Gettext Functions

Table of Contents

bind_textdomain_codeset> <Predefined Constants
[edit] Last updated: Sat, 12 May 2012
add a note add a note User Contributed Notes Gettext Functions
analpaper{gmail} 28-Aug-2008 02:36
in response to richard:
i was using the wildcard * for sometime ago without problem, until today.

i used:
<?php bindtextdomain( '*', './locale' ); ?>
but it seems to fail under some environments (i dont know why, but in diff machines with same software the result is not always as expected)..

then, with:
<?php bindtextdomain( "*", './locale' ); ?>
all is nicely translated again.

i use single quotes always if possible, now there are another think to remember.
Sbastien Ballest-Antich 21-May-2008 06:08
A workaround to use heredoc and gettext strings with sprintf :
= <<<EOD
$hdgt = sprintf($hd, _('Heredoc'), _('gettext'));
titan at phpdevshell dot org 07-Mar-2008 11:25
If you would like to create a .po file with include heredoc scripts inside curly brackets {} solution is as follows;

I want to translate what in here (test.php):
= <<<EOF
$t->__('I want to translate this string.')}

You will have to use the xgettext (gnu utility) with the Python parser like so:
$ xgettext --default-domain=test --keyword=__ --keyword --language=Python test.php

The above terminal command might seem wrong with --keyword used twice, this is however correct.
SEWilco 25-Jul-2007 02:21
People have suggested several combinations of configuration options.  Consider trying nested loops with various combinations of language names (with and without character set suffixes) and pathnames.  A gettext() call in the middle of the loops can test for success (a string being translated).

"Of 4374 localization setup variations tested there were 0 successes."

Sometimes one just has to fix the system and PHP configuration.
jon at nospam dot foo 25-Apr-2007 03:37
I'm sure I'll confuse further, but I feel compelled to chime in.  I got stuck on this a bit...

It's absolutely critical that your gettext installation supports the locale you are trying to use in your setlocale(LC_MESSAGES,$locale) call.

This does not work:


in OpenSUSE 10.2, because /usr/lib/locale does not contain the directory "en" (out of the box), even though your custom LC_MESSAGES domain location might.

In OpenSUSE 10.2, at least, /usr/lib/locale contains for USA English:


(again, not "en").

It might be possible to set up an alias, I'm not sure (does anyone have a idea about this).

My goal was to use HTTP_ACCEPT_LANGUAGE to set locale (I realize that locale != language, but it seems that gettext uses locale to assign language (scratches head) ).  Opera in OS X does not send "en_US".  However, Firefox does out of the box.  I'm not sure if it's supposed to work this way, but it seems like it should, and so the way Opera handles this appears to be an issue.  Incidentally, Safari simples send "en" in HTTP_ACCEPT_LANGUAGE, and will also not work.

This compelled me to set a configurable default locale (e.g "en_US") in my PHP app, which one probably should do anyway, because HTTP_ACCEPT_LANGUAGE might be blank.
jeremy at jeremy dot se dot nospam 20-Feb-2007 11:27
As some of you have mentioned, you must have the locales compiled on your system first. How this is done is depending on your system/distribution *sigh*

In every case you need to have gettext installed on your system. Users running a Linux with a recent version of libc will have gettext in libc already.

Here's an example for those of you running Ubuntu Edgy.

First of all, have a look in /usr/share/i18n/SUPPORTED, here are the locales that are supported on your system. To compile a locale we will use the command "locale-gen". ("man 8 locale-gen" is good reading)

This command reads configuration from files in the folder /var/lib/locales/supported.d/ In these files the locales and charsets are defined.

If we take swedish as an example, start by creating a file called "sv" in /var/lib/locales/supported.d/ and then put in something like "sv_SE.UTF8 UTF8" (without the " ") This says that we want the locale sv_SE to be built with charmap UTF-8. Check the file /usr/share/i18n/SUPPORTED for other alternatives.

Now we run "locale-gen" which will compile all locales defined in /var/lib/locales/supported.d/ and put them in /usr/lib/locales (yes that's a lot of locations...)

Now you're ready to go...

Create a php-file (e.g. hello.php) where all strings you want to translate are surrounded with _("string here");

next run "xgettext hello.php", this creates a file called messages.po, which is you translation-file (pot). Change the "Content-Type: text/plain; charset=CHARSET\n" in this file and replace CHARSET with UTF-8 in this case. Next translate all strings like this.

#: hello.php:3
msgid "hello!"
msgstr "hej!"

Save and use the command "msgfmt -o messages.po" which will create a compiled .mo file called

This file is then placed in a directory structure somewhere your Apache can read it. The structure looks like this:


Next, let php know what we're doing. We point to where we have our translations. Add the following at the top of hello.php


This binds the file to the locale/ directory you created.
Then set the locale. LC_ALL tells that we want everything translated. Might not be good at all times, as another person here suggested.

setlocale(LC_ALL, "sv_SE.UTF-8");

Finally select the that we want to use


That should be it! Try it out..

If you get any problems try restarting Apache as it seems to cache the locales.

If you are running command line you might have to set the environment variable LANGUAGE to your locale as well. I didn't have to do that to get it working in apache though, but you might...

djogopatrao at gmail dot com 31-Oct-2006 03:57
Juan Liska, I found an alternative. Instead of renaming or adding a alias to the locale, I simply changed

$language = 'pt_BR';


$language = 'pt_BR.UTF-8';
setlocale(LC_ALL, $language)

and it did work fine!
konrads/smelkovs/gmail/com 11-Oct-2006 07:16
re LC_MESSAGES for windows users, LC_MESSAGES should be defi0ned as 5
C Snover 13-Aug-2006 04:26
I think that it bears mentioning that most documentation and tutorials you will find say that you should setenv(LC_ALL, $locale), but this only works IF THE LOCALE IS VALID ON THE LOCAL MACHINE. If you are using a locale that does not exist on the system or is not valid (like something returned from the HTTP Accept-Language header, such as 'ja', which is never a valid locale because it does not include the country code JP), you will probably be pulling your hair out for HOURS trying to figure out why the damn thing isn't working.

What I have found is that setting the LANGUAGE variable (eg. setenv("LANGUAGE=$locale")) will allow gettext to search inside your locale directories, even if the locale is not actually valid on the local system.

So, to summarize:

This will work:
= 'ja'; // Pretend this came from the Accept-Language header
$locale_dir = './locale'; // your .po and .mo files should be at $locale_dir/$locale/LC_MESSAGES/messages.{po,mo}

bindtextdomain('messages', $locale_dir);

This will not work:
= 'ja';
$locale_dir = './locale';

bindtextdomain('messages', $locale_dir);

This will also not work:
= 'ja';
$locale_dir = './locale';

setlocale(LC_ALL, $locale);
bindtextdomain('messages', $locale_dir);

Nor will this work:
= 'ja';
$locale_dir = './locale';

setlocale(LC_MESSAGES, $locale);
bindtextdomain('messages', $locale_dir);

For reference, this was tested on PHP 5.1.2 + LigHTTPd 1.4.11 + gettext 0.14.5 on Ubuntu Dapper 6.06. It should be true for any variant of Linux, however, as well as older versions of these software packages.
richard at hirner dot at 13-Jul-2006 04:43
the * wildcard doesn't work for me (php 5)... I have to use bindtextdomain for each textdomain
webmaster [at] ttw [dash] tool [dot] de 21-May-2006 04:49
If you want to use messages from multiple domains with .mo-files residing in non-standard locations remember to place a bindtextdomain()-call for each domain as "unbound" domains will be looked for in the standard location (usually "/usr/share/locale" on *nix)



dgettext('foo','Text to be translated using the foo-catalog.');
dgettext('bar','Text from a different catalog named bar.');


If all the .mo-files you are using reside in one and the same directory, you may use the "*"-wildcard like this:




This code was tested on PHP 5.1.4
info at adaniels dot nl 19-Apr-2006 12:19
As stated by robert at klugher dot com:
The environment setting 'LANGUAGE' gets priority above any local setting. This means that changing LC_ALL/LC_MESSAGES and LANG as done in almost all examples, won't do anything.

So if you've done
= "nl_NL";
setlocale(LC_ALL, $language);
but the text is still displayed in english. Try also setting the LANGUAGE variable.
= "nl_NL";
setlocale(LC_ALL, $language);
birkholz at web dot de 28-Mar-2006 09:52
> stefan+usenet at froehlich dot priv dot at wrote at 5-May-2004 01:30:
> 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.

For all Windows-Users:
Be warned the LC_MESSAGES seems to be NOT set on Windows with PHP 5.1.2, so if you develope applications for a Linux-System and want to make it multi-language using gettext, you will get problems using LC_MESSAGES on your Windows-Developement-Box.
You can try to solve this problem by putting a

<?php if (!defined('LC_MESSAGES')) define('LC_MESSAGES', 6); ?>

to your script to get no warning if you pass LC_MESSAGES to the setlocale()-function.
Juan Liska 15-Nov-2005 03:09
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:


you now have the locales you want, not just the ones the system magically came with
milky#users:sf/net 09-Jun-2005 06:12
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 [ ] tarball.  Support for plural translations isn't there, because that is too hard to get reimplemented reliably.
tucsi at c2 dot hu 18-May-2005 04:09
If your gettext translation does not work in safe mode, than try to set this in the php.ini:
safe_mode_allowed_env_vars = PHP_,LANG
Maxwel Leite -maxwelleite at gmail com- 27-Apr-2005 12:36
PHP-gettext is developed to be able to read gettext MO files directly, without requiring anything other than PHP:
elonen at iki dot fi 30-Mar-2005 01:51
For making localized copies of PHP files (statical l10n), here's a GPL'd command line tool:
dpatton at confluence dot org 27-Feb-2005 10:47
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:
susko at seznam dot cz 24-Feb-2005 09:09
Gettext returning question marks instead of some local characters? Try using bind_textdomain_codeset to change codeset of the translated messages:

bind_textdomain_codeset (domain, codeset);

It worked for me, hope it works for you ..
zixia at zixia dot net 11-Jun-2004 02:42
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.
mikolaj at webgate dot bg 10-Jun-2004 04:54
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

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:
// translation file: D:\Apache\htdocs\mypage\locale\bgr_BGR\LC_MESSAGES\
bindtextdomain('messages', 'D:\Apache\htdocs\mypage\locale\\');
stefan+usenet at froehlich dot priv dot at 05-May-2004 04:30
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.
kocio at irc dot pl 03-May-2004 03:26
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');

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.
dev.php at 26-Aug-2003 07:35
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)
wouter at grep dot be 13-Aug-2003 12:28
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

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.
jc 14-Jul-2003 01:15
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");
anim8 17-Jun-2003 06:15
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

13-Jun-2003 07:41
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!
Picco 08-Jun-2003 10:45
Note to Chinese programmers....

Took me hours to figure out you cannot use

but have to use
on some machines...

a good way to test will be to check the return of setlocale()
robert at klugher dot com 25-Feb-2003 09:03
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:


Then, if ever you script always translate to the same language, check the value of LANGUAGE ...
robert at klugher dot com 25-Feb-2003 05:24
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.

zw at matfyz dot cz 05-Feb-2003 10:38
There is a nice tutorial on using gettext with php
php at zpod dot ca 29-Jan-2003 07:24
For those of you just trying to get a script working and your provider doesn't support gettext, you can bypass the international stuff by adding this:

function _($str) {
    return $str;
Eneko Lacunza enlar at enlar dot net 16-Jan-2003 08:20
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));

// Set the language as full locale 'es_ES'
$language = 'es_ES';
setlocale(LC_ALL, $language);

// Set the text domain as 'mydomain'
$domain = 'mydomain';
bindtextdomain("$domain", "./locale");

// The .mo file searched is:
// ./locale/es_ES/LC_MESSAGES/
// or if previous one doesn't exist:
// ./locale/es/LC_MESSAGES/

echo gettext("Hello world!");

Hope this helps!
yledoare at free dot fr 15-Jan-2003 07:32
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 ( with gettext package ( to make it work under WinXp.

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

Here is my conv.bat to generate french translation :

set path=c:\mingw\bin
msgfmt -v -o greetings.po

That's all !

Yann Le Doar, Brest, France
ywliu atsign hotmail com 09-Jul-2002 09:39

For users with Red Hat GNU/Linux (at least 6.2) to use gettext, I'd like to make some notes here :

1. Calling setlocale() is necessary, where calling putenv('LANG=xx_YY') or putenv('LC_ALL=xx_YY') is not.

2. The country/language code should be in the "language_country" form,such as, "en_US" or "fr_FR", or any entry in /usr/share/locale/locale.aliase . The simple ISO two-letter code, such as "en" , is not valid. You can examine the return value of setlocale to see if the locale setting succeeds.

This took me several hours to debug. I hope my experience can save you some time.

This may apply to other Linux distributions or *BSD systems. I don't know. I hope this helps.

Yen-Wei Liu
php at dynaperl dot com 25-Jun-2002 06:49
If you install from SuSE Dist. you need glibc-locale.rpm to let gettext work.

mfg ralph.
mgvNOSPAM at fx dot ro 04-Jun-2002 07:47
If you're as clueless as I am, please note the following:
1. Although most comments list setlocal() in the code, that's not actually required for translations - read the docs under "string functions" for details (also, the official gettext() examples don't include it);
2. hace_x's example is really cool, except you need to know that all "n"'s at the end of his strings should have a backslash before - they're actually EOL characters, but they somehow got messed up and I needed two hours to find that out...
hace_x at yahoo dot com 15-Nov-2001 05:40
I had alot of problems to get gettext() to work on my windows2000-php webserver. The following will give those windows-php users something to hold on to:

Note the way you have to use slashes for the bindtextdomain command:

For a 'greetings' domain:

bindtextdomain ("greetings", ".\includes\translations");

(so, TWO slashes instead of one between the folder-names!)

ALSO, I had to change the filename to be '': This was NOT clear from all the gnu-pages I read. I had named those files: (for dutch) and (for french etcetera).

I provide my code and folder-structure here for other windows-users:

("Content-type: text/plain");
// Bind a domain to directory
// Gettext uses domains to know what directories to
// search for translations to messages passed to gettext

bindtextdomain ("greetings", "./includes/translations"); // Set the current domain that gettext will use
textdomain ('greetings'); # Make an array

# Use the ISO two-letter codes as keys
# Use the language names as values
$iso_codes = array (
foreach (
$iso_codes as $iso_code => $language) {
# Set the LANGUAGE environment variable to the desired language
putenv ('LANG='.$iso_code); # Print out the language name and greeting
# Filter the greeting through gettext

printf ("%12s: %s\n", $language, gettext("str_hello")) & "\n";


In the windows-webfolder I have the following directory-structure:


To get this working you will need a greetings.po file like this:

(this one is in the 'nl' subdir for dutch language):
msgid ""
msgstr ""
"Project-Id-Version: n"
"POT-Creation-Date: n"
"PO-Revision-Date: 2001-11-14 17:11+0100n"
"Last-Translator: Melle Koning <>n"
"Language-Team:  <>n"
"MIME-Version: 1.0n"
"Content-Type: text/plain; charset=utf-8n"
"Content-Transfer-Encoding: 8bitn"

msgid "str_hello"
msgstr "hallo"

and you have to 'compile' this .po file to a .mo file with the following command-line (go to windows 'command prompt'):

msgfmt -o greetings.po

To get msgfmt working on your windows machine, you will need to have libiconv.dll, libintl.dll and msgfmt.exe in your path. What I did was put these three files in a new c:utils folder and than run the command:

I hope this helps some windows-users like me to get gettext() to work on their systems.......

Michele dot Manzato at verona dot miz dot it 14-Sep-2001 03:52
Gettext is great, but there are a few caveats you have to consider in order to make it work. Unfortunately the gettext docs isn't so plain and clear...

The .mo file created with the gettext utilities must be:

[bindtextdomain's dir]/[language]/LC_MESSAGES/[domain].mo

otherwise gettext() function will fail to find it (this is true in win32, don't know about Un*ces). By the way you don't get any error message, the strings will simply remain untranslated.

Second, you must make sure which is the current directory if you use a relative path in bindtextdomain. On some systems the script directory isn't the current directory, so you have to chdir() there.

Then, of course, make sure that the appropriate gettext extension are loaded by PHP by looking at the php configuration file.

Here is some sample code:

// Change to the script directory
$path = dirname(getenv(PATH_TRANSLATED));

// Set the language as 'it'
$language = 'it';
setlocale(LC_ALL, $language);

// Set the text domain as 'mydomain'
$domain = 'mydomain';
bindtextdomain("$domain", "./locale");

// The .mo file searched is:
// ./locale/it/LC_MESSAGES/

echo gettext("Hello world!");

Have fun!
12-Jul-2001 04:59
To get xgettext working with my php code I had to change simple quotes to double quites in my previous example :

if($err)printf(dGetText("errorMsg","you have an error here"));

I guess that's because strings can not be simple-quoted in C. However I think it is good practice to do as if it was a simple quote, because you do not want to interpolate a string that will end in the catalogue.

11-Jul-2001 05:40
It is probably obvious to many of you,  but I thought it was worth mentioning that the domain is the name of the .mo files that contain the string catalogue (without the extension).

so if you have a catalogue for each page in './locale/lg/LC_MESSAGE' and some generic catalogues (e.g. in '/global/locale/lg/LC_MESSAGE', you can do

bindTextDomain("$myPage", './locale');
bindTextDomain('errorMsg','/global/locale' );
if($err)printf(dGetText('errorMsg','you have an error here'));


show source | credits | sitemap | contact | advertising | mirror sites