Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Locale::Codes(3)       Perl Programmers	Reference Guide	      Locale::Codes(3)

       Locale::Codes - a distribution of modules to handle locale codes

       Locale-Codes is a distribution containing a set of modules.  The
       modules each deal with different	types of codes which identify parts of
       the locale including languages, countries, currency, etc.

       Currently, the following	modules	are included:

       Locale::Codes::Country, Locale::Country
	   This	includes support for country codes (such as those listed in
	   ISO-3166) to	specify	the country.

	   Because this	module was originally distributed as Locale::Country,
	   it is also available	under that name.

       Locale::Codes::Language,	Locale::Language
	   This	includes support for language codes (such as those listed in
	   ISO-639) to specify the language.

	   Because this	module was originally distributed as Locale::Language,
	   it is also available	under that name.

       Locale::Codes::Currency,	Locale::Currency
	   This	includes support for currency codes (such as those listed in
	   ISO-4217) to	specify	the currency.

	   Because this	module was originally distributed as Locale::Currency,
	   it is also available	under that name.

       Locale::Codes::Script, Locale::Script
	   This	includes support for script codes (such	as those listed	in
	   ISO-15924) to specify the script.

	   Because this	module was originally distributed as Locale::Script,
	   it is also available	under that name.

	   This	includes support for language extension	codes (such as those
	   listed in the IANA language registry) to specify the	language

	   This	includes support for language variation	codes (such as those
	   listed in the IANA language registry) to specify the	language

	   This	includes support for language family codes (such as those
	   listed in ISO 639-5)	to specify families of languages.

       Each module can support an arbitrary number of code sets, and it	is not
       required	that the relationship between these code sets be one-to-one.
       For example, the	Locale::Codes::Country module supports code sets from
       ISO-3166	and the	IANA standard, and those two standards do not break
       the world down into exactly the same sets of countries. This does not
       cause any problem (though converting codes from ISO-3166	to IANA	or
       back will not work except for countries that are	one-to-one).

       All data	in all of these	modules	comes directly from the	original
       standards (or as	close to direct	as possible), so it should be up-to-
       date at the time	of release.

       I plan on releasing a new version several times a year to incorporate
       any changes made	in the standards. However, I don't always know about
       changes that occur, so if any of	the standards change, and you want a
       new release sooner, just	email me and I'll get one out.

       In addition to the modules above, there are a number of support modules
       included	in the distribution including:


       These modules are not intended to be used by programmers. They contain
       functions or data that are used by the modules listed above.  No
       support of any kind is offered for using	these modules directly.	 They
       may be modified at any time.

       I'm always open to suggestions for new code sets.

       In order	for me to add a	code set, I want the following criteria	to be

       General-use code	set
	   If a	code set is not	general	use, I'm not likely to spend the time
	   to add and support it.

       An official source of data
	   I require an	official (or at	least, a NEARLY	official) source where
	   I can get the data on a regular basis.

	   Ideally, I'd	only get data from an official source, but sometimes
	   that	is not possible. For example the ISO standards are not
	   typically available for free, so I may have to get some of that
	   data	from alternate sources that I'm	confident are getting their
	   data	from the official source.  However, I will always be hesitant
	   to accept a non-official source.

	   As an example, I used to get	some country data from the CIA World
	   Factbook. Given the nature of the source, I'm sure they're updating
	   data	from the official sources and I	consider it "nearly" official.
	   However, even in this case, I found that they were adding codes
	   that	were not part of the standard, so I have stopped using them as
	   a source.

	   There are many 3rd party sites which	maintain lists (many of	which
	   are actually	in a more convenient form than the official sites).
	   Unfortunately, I will reject	most of	them since I have no feel for
	   how "official" they are.

       A free source of	the data
	   Obviously, the data must be free-of-charge. I'm not interested in
	   paying for the data (and I'm	not interested in the overhead of
	   having someone else pay for the data	for me).

       A reliable source of data
	   The source of data must come	from a source that I can reasonably
	   expect to exist for the foreseeable future since I will be
	   extremely reluctant to drop support for a data set once it's

	   I am	also reluctant to accept data sent to me by an individual.
	   Although I appreciate the offer, it is simply not practical to
	   consider an individual contribution as a reliable source of data.
	   The source should be	an official agency of some sort.

       These requirements are open to discussion. If you have a	code set you'd
       like to see added, but which may	not meet all of	the above
       requirements, feel free to email	me and we'll discuss it.  Depending on
       circumstances, I	may be willing to waive	some of	these criteria.

       As of version 2.00, the modules supported common	variants of names.

       For example, Locale::Country supports variant names for countries, and
       a few of	the most common	ones are included in the data. The country
       code for	"United	States"	is "us", so:

	  country2code('United States');
	    => "us"

       Now the following will also return 'us':

	  country2code('United States of America');

       Any number of common aliases may	be included in the data, in addition
       to the names that come directly from the	standards.  If you have	a
       common alias for	a country, language, or	any other of the types of
       codes, let me know and I'll add it, with	some restrictions.

       For example, the	country	name "North Korea" never appeared in any of
       the official sources (instead, it was "Korea, North" or "Korea,
       Democratic People's Republic of". I would honor a request to add	an
       alias "North Korea" since that's	a very common way to specify the
       country (please don't request this... I've already added	it).

       On the other hand, a request to add Zaire as an alias for "Congo, The
       Democratic Republic of" will not	be honored. The	country's official
       name is no longer Zaire,	so adding it as	an alias violates the
       standard.  Zaire	was kept as an alias in	versions of this module	prior
       to 3.00,	but it has been	removed. Other aliases (if any)	which no
       longer appear in	any standard (and which	are not	common variations of
       the name	in the standards) have also been removed.

       Occasionally, a code is deprecated, but it may still be desirable to
       have access to it.

       Although	there is no way	to see every code that has ever	existed	and
       been deprecated (since most codesets do not have	that information
       available), as of version 3.20, every code which	has ever been included
       in these	modules	can be referenced.

       For more	information, refer to the documentation	on the code2XXX,
       XXX2code, all_XXX_codes,	and all_XXX_names function in the
       Locale::Codes::API documentation.

	   The list of functions available in each of the modules listed
	   below.  The APIs for	each module are	exactly	identical.

	   Codes for identification of countries.

	   Codes for identification of languages.

	   Codes for identification of scripts.

	   Codes for identification of currencies and funds.

	   Codes for identification of language	extensions.

	   Codes for identification of language	variations.

	   Codes for identification of language	families.

	   A history of	changes	made to	this distribution.

       If you find a bug in Locale::Codes, there are three ways	to send	it to
       me.  Any	of them	are fine, so use the method that is easiest for	you.

       Direct email
	   You are welcome to send it directly to me by	email.	The email
	   address to use is:

       CPAN Bug	Tracking
	   You can submit it using the CPAN tracking too.  This	can be done at
	   the following URL:


	   You can submit it as	an issue on GitHub.  This can be done at the
	   following URL:


       Please do not use other means to	report bugs (such as Usenet
       newsgroups, or forums for a specific OS or Linux	distribution) as it is
       impossible for me to keep up with all of	them.

       When filing a bug report, please	include	the following information:

       Locale::Codes version
	   Please include the version of Locale::Codes you are using.  You can
	   get this by using the script:

	      use Locale::Codes::Country;
	      print $Locale::Codes::VERSION,"\n";

       If you want to report missing or	incorrect codes, you must be running
       the most	recent version of Locale::Codes.

       If you find any problems	with the documentation (errors,	typos, or
       items that are not clear), please send them to me. I welcome any
       suggestions that	will allow me to improve the documentation.

       Locale::Country and Locale::Language were originally written by Neil
       Bowers at the Canon Research Centre Europe (CRE). They maintained the
       distribution from 1997 to 2001.

       Locale::Currency	was originally written by Michael Hennecke and was
       modified	by Neil	Bowers for inclusion in	the distribution.

       From 2001 to 2004, maintenance was continued by Neil Bowers.  He
       modified	Locale::Currency for inclusion in the distribution. He also
       added Locale::Constants and Locale::Script.

       From 2004-2009, the module was unmaintained.

       In 2010,	maintenance was	taken over by Sullivan Beck (
       with Neil Bower's permission.  All problems or comments should be sent
       there.  Alternately, problems can be reported using the perl problem
       tracker at:


	  Copyright (c)	1997-2001 Canon	Research Centre	Europe (CRE).
	  Copyright (c)	2001	  Michael Hennecke (Locale::Currency)
	  Copyright (c)	2001-2010 Neil Bowers
	  Copyright (c)	2010-2016 Sullivan Beck

       This module is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.

perl v5.26.0			  2017-04-19		      Locale::Codes(3)


Want to link to this manual page? Use this URL:

home | help