xref: /PHP-5.3/ext/intl/doc/locale_api.php (revision 9762609c)
1<?php
2
3/**
4 * A "Locale" is an identifier used to get language, culture, or regionally-specific
5 * behavior from an API. PHP locales are organized and identified the same
6 * way that the CLDR locales used by ICU (and many vendors of Unix-like operating
7 * systems, the Mac, Java, and so forth) use. Locales are identified using
8 * RFC 4646 language tags (which use hyphen, not underscore) in addition to the
9 * more traditional underscore-using identifiers. Unless otherwise noted
10 * the functions in this class are tolerant of both formats.
11 *
12 * Examples of identifiers include:
13 *
14 *  * en-US (English, United States)
15 *  * zh-Hant-TW (Chinese, Traditional Script, Taiwan)
16 *  * fr-CA, fr-FR (French for Canada and France respectively)
17 *
18 * The Locale class (and related procedural functions) are used to interact
19 * with locale identifiers--to verify that an ID is well-formed, valid,
20 * etc. The extensions used by CLDR in UAX #35 (and inherited by ICU) are
21 * valid and used wherever they would be in ICU normally.
22 *
23 * Locales cannot be instantiated as objects. All of the functions/methods
24 * provided are static.
25 *
26 *   * The null or empty string obtains the "root" locale.
27 *     The "root" locale is equivalent to "en_US_POSIX" in CLDR.
28 *   * Language tags (and thus locale identifiers) are case insensitive. There
29 *     exists a canonicalization function to make case match the specification.
30 *
31 * @see http://www.icu-project.org/apiref/icu4c/uloc_8h.html
32 * @see http://www.unicode.org/reports/tr35/
33 *
34 */
35class Locale {
36
37#############################################################################
38# Common constants.
39#############################################################################
40
41   	/**
42     	 * The following static members are used with the getLocale methods of
43     	 * the various locale affected classes, such as numfmt.
44     	 */
45  	const DEFAULT_LOCALE 			= null;
46
47   	/**
48	 * identifiers for the actual locale, valid locale
49 	 * WARNING:
50	 * The values described here are NOT the actual values in PHP code.
51	 * They are references to the ICU C definitions, so the line
52	 *    const ACTUAL_LOCALE = 'ULOC_ACTUAL_LOCALE';
53	 * actually means that Locale::ACTUAL_LOCALE is the same as
54	 * ULOC_ACTUAL_LOCALE constant in the ICU library.
55	 */
56	const ACTUAL_LOCALE 			= 'ULOC_ACTUAL_LOCALE';
57   	const VALID_LOCALE 			= 'ULOC_VALID_LOCALE';
58
59	/**
60	 * Valid locale tag and subtag values
61	 */
62	const LANG_TAG 				= "language";
63	const EXTLANG_TAG 			= "extlang";
64	const SCRIPT_TAG 			= "script";
65	const REGION_TAG 			= "region";
66	const VARIANT_TAG 			= "variant";
67	const GRANDFATHERED_LANG_TAG 		= "grandfathered";
68	const PRIVATE_TAG 			= "private";
69
70
71#############################################################################
72# Object-oriented API
73#############################################################################
74
75	/**
76	 * Gets the default locale value from the INTL global 'default_locale'
77	 * At the PHP initilaization (MINIT) this value is set to
78	 * 'intl.default_locale' value from php.ini if that value exists
79	 * or from ICU's function  uloc_getDefault()
80	 * Then onwards picks up changes from setDefault() calls also
81	 *
82     	 * @return string the current runtime locale
83     	 */
84	public static function getDefault() {}
85
86	/**
87     	 * sets the default runtime locale to $locale
88 	 * This changes the value of INTL global 'default_locale'
89     	 *
90     	 * @param 	string	 $locale 	is a BCP 47 compliant language tag containing the
91     	 *					locale identifier. UAX #35 extensions are accepted.
92     	 * @return	boolean 		'true' if okay, 'false' if an error
93     	 */
94    	public static function setDefault($locale) {}
95
96
97    	/**
98	 * Gets the primary language for the input locale
99	 *
100     	 * @param	string	$locale 	the locale to extract the primary language code from
101     	 * @return 	string 			the language code associated with the language
102	 *					or null in case of error.
103     	 */
104    	public static function getPrimaryLanguage($locale) {}
105
106
107    	/**
108	 * Gets the script for the input locale
109	 *
110     	 * @param 	string 	$locale 	the locale to extract the script code from
111     	 * @return 	string 			the script subtag for the locale or null if not present
112     	 */
113    	public static function getScript($locale) {}
114
115
116    	/**
117	 * Gets the region for the input locale
118	 *
119     	 * @param 	string 	$locale 	the locale to extract the region code from
120     	 * @return 	string 			the region subtag for the locale or null if not present
121     	 */
122    	public static function getRegion($locale) {}
123
124
125    	/**
126	 * Gets the variants for the input locale
127	 *
128    	 * @param 	string 	$locale 	the locale to extract the variants from
129     	 * @return 	array 			the array containing the list of all variants
130	 *					subtag for the locale or null if not present
131     	 */
132	public static function getAllVariants($locale) {}
133
134
135	/**
136	 * Gets the keywords for the input locale
137	 *
138     	 * @param 	string 	$locale 	the locale to extract the keywords from
139     	 * @return 	array 			associative array containing the keyword-value pairs for this locale
140     	 */
141    	public static function getKeywords($locale) {}
142
143
144    	/**
145	 * Returns an appropriately localized display name for the input locale
146	 *
147    	 * @param 	string 	 	$locale 	the locale to return a displayname for
148	 * @param 	[string] 	$in_locale  	optional format locale
149	 * 						If is 'null' then the default locale is used.
150	 * @return 	string  			display name of the locale in the format
151	 * 						appropriate for $in_locale.
152     	 */
153    	public static function getDisplayName($locale, $in_locale = null) {}
154
155
156    	/**
157	 * Returns an appropriately localized display name for language of the input locale
158	 *
159     	 * @param 	string 	 	$locale 	the locale to return a display language for
160	 * @param 	[string] 	$in_locale  	optional format locale to use to display the language name
161	 * 						If is 'null' then the default locale is used.
162	 * @return 	string  			display name of the language for the $locale in the format
163	 * 						appropriate for $in_locale.
164     	 */
165	public static function getDisplayLanguage($lang, $in_locale = null) {}
166
167    	/**
168	 * Returns an appropriately localized display name for script of the input locale
169	 *
170    	 * @param 	string 	 	$locale 	the locale to return a display script for
171	 * @param 	[string] 	$in_locale  	optional format locale to use to display the script name
172	 * 						If is 'null' then the default locale is used.
173	 * @return 	string  			display name of the script for the $locale in the format
174	 * 						appropriate for $in_locale.
175     	 */
176	public static function getDisplayScript($script, $in_locale = null) {}
177
178
179    	/**
180	 * Returns an appropriately localized display name for region of the input locale
181	 *
182    	 * @param 	string 	 	$locale 	the locale to return a display region for
183	 * @param 	[string] 	$in_locale  	optional format locale to use to display the region name
184	 * 						If is 'null' then the default locale is used.
185	 * @return 	string  			display name of the region for the $locale in the format
186	 * 						appropriate for $in_locale.
187     	 */
188	public static function getDisplayRegion($region, $in_locale = null) {}
189
190
191    	/**
192	 * Returns an appropriately localized display name for variants of the input locale
193	 *
194    	 * @param 	string 	 	$locale 	the locale to return a display variant for
195	 * @param 	[string] 	$in_locale  	optional format locale to use to display the variant name
196	 * 						If is 'null' then the default locale is used.
197	 * @return 	string  			display name of the variant for the $locale in the format
198	 * 						appropriate for $in_locale.
199     	 */
200	public static function getDisplayVariant($variant, $in_locale = null) {}
201
202
203    	/**
204	 * Checks if a $langtag  filter matches with $locale according to
205	 * RFC 4647's basic filtering algorithm
206	 *
207     	 * @param 	string 		$langtag	the language tag to check
208	 * @param 	string 		$locale		the language range to check against
209	 * @param 	bool 		$canonicalize	Canonicalize parameters?
210     	 * @return 	boolean 			'true' if $locale matches $langtag 'false' otherwise
211	 */
212    	public static function filterMatches($langtag, $locale, $canonicalize) {}
213
214	/**
215     	 * Searchs the items in $langtag for the best match to the language
216	 * range specified in $locale according to RFC 4647's lookup algorithm.
217	 *
218	 * @param 	array 		$langtag  	an array containing a list of language tags to compare
219	 *            					to $locale
220	 * @param 	string 		$locale   	the locale to use as the language range when matching
221	 * @param 	string 		$default  	the locale to use if no match is found
222	 * @return 	string 				closest matching language tag, $default,
223	 *						or empty string
224	 */
225    	public static function lookup(array $langtag, $locale, $default = null) {}
226
227
228	/**
229     	 * Returns a correctly ordered and delimited locale ID
230	 *
231	 * @param 	array 		$subtags 	an array containing a list of key-value pairs, where
232	 * 						the keys identify the particular locale ID subtags,
233	 *						and the values are the associated subtag values.
234	 *
235	 * @return 	string 				the corresponding locale identifier.
236	 */
237    	public static function composeLocale(array $subtags) {}
238
239
240	/**
241	 * Returns a key-value array of locale ID subtag elements.
242	 *
243	 * @param 	string		$locale		the locale to extract the subtag array from
244	 *
245	 * @return 	array 		$subtags 	an array containing a list of key-value pairs, where
246	 * 						the keys identify the particular locale ID subtags,
247	 *						and the values are the associated subtag values.
248	 */
249    	public static function parseLocale($locale) {}
250
251}
252
253#############################################################################
254# Procedural API
255#############################################################################
256
257
258	/**
259	 * Gets the default locale value from the INTL global 'default_locale'
260	 * At the PHP initilaization (MINIT) this value is set to
261	 * 'intl.default_locale' value from php.ini if that value exists
262	 * or from ICU's function  uloc_getDefault()
263	 * Then onwards picks up changes from setDefault() calls also
264	 *
265     	 * @return string the current runtime locale
266     	 */
267	 function locale_get_default() {}
268
269	/**
270     	 * sets the default runtime locale to $locale
271 	 * This changes the value of INTL global 'default_locale'
272     	 *
273     	 * @param 	string	 $locale 	is a BCP 47 compliant language tag containing the
274     	 *					locale identifier. UAX #35 extensions are accepted.
275     	 * @return	boolean 		'true' if okay, 'false' if an error
276     	 */
277    	 function locale_set_default($locale) {}
278
279
280    	/**
281	 * Gets the primary language for the input locale
282	 *
283     	 * @param	string	$locale 	the locale to extract the primary language code from
284     	 * @return 	string 			the language code associated with the language
285	 *					or null in case of error.
286     	 */
287    	 function locale_get_primary_language($locale) {}
288
289
290    	/**
291	 * Gets the script for the input locale
292	 *
293     	 * @param 	string 	$locale 	the locale to extract the script code from
294     	 * @return 	string 			the script subtag for the locale or null if not present
295     	 */
296    	 function locale_get_script($locale) {}
297
298
299    	/**
300	 * Gets the region for the input locale
301	 *
302     	 * @param 	string 	$locale 	the locale to extract the region code from
303     	 * @return 	string 			the region subtag for the locale or null if not present
304     	 */
305    	 function locale_get_region($locale) {}
306
307
308    	/**
309	 * Gets the variants for the input locale
310	 *
311    	 * @param 	string 	$locale 	the locale to extract the variants from
312     	 * @return 	array 			the array containing the list of all variants
313	 *					subtag for the locale or null if not present
314     	 */
315	 function locale_get_all_variants($locale) {}
316
317
318	/**
319	 * Gets the keywords for the input locale
320	 *
321     	 * @param 	string 	$locale 	the locale to extract the keywords from
322     	 * @return 	array 			associative array containing the keyword-value pairs for this locale
323     	 */
324    	 function locale_get_keywords($locale) {}
325
326
327    	/**
328	 * Returns an appropriately localized display name for the input locale
329	 *
330    	 * @param 	string 	 	$locale 	the locale to return a displayname for
331	 * @param 	[string] 	$in_locale  	optional format locale
332	 * 						If is 'null' then the default locale is used.
333	 * @return 	string  			display name of the locale in the format
334	 * 						appropriate for $in_locale.
335     	 */
336    	 function locale_get_display_name($locale, $in_locale = null) {}
337
338
339    	/**
340	 * Returns an appropriately localized display name for language of the input locale
341	 *
342     	 * @param 	string 	 	$locale 	the locale to return a display language for
343	 * @param 	[string] 	$in_locale  	optional format locale to use to display the language name
344	 * 						If is 'null' then the default locale is used.
345	 * @return 	string  			display name of the language for the $locale in the format
346	 * 						appropriate for $in_locale.
347     	 */
348	 function locale_get_display_language($lang, $in_locale = null) {}
349
350    	/**
351	 * Returns an appropriately localized display name for script of the input locale
352	 *
353    	 * @param 	string 	 	$locale 	the locale to return a display script for
354	 * @param 	[string] 	$in_locale  	optional format locale to use to display the script name
355	 * 						If is 'null' then the default locale is used.
356	 * @return 	string  			display name of the script for the $locale in the format
357	 * 						appropriate for $in_locale.
358     	 */
359	 function locale_get_display_script($script, $in_locale = null) {}
360
361
362    	/**
363	 * Returns an appropriately localized display name for region of the input locale
364	 *
365    	 * @param 	string 	 	$locale 	the locale to return a display region for
366	 * @param 	[string] 	$in_locale  	optional format locale to use to display the region name
367	 * 						If is 'null' then the default locale is used.
368	 * @return 	string  			display name of the region for the $locale in the format
369	 * 						appropriate for $in_locale.
370     	 */
371	 function locale_get_display_region($region, $in_locale = null) {}
372
373
374    	/**
375	 * Returns an appropriately localized display name for variants of the input locale
376	 *
377    	 * @param 	string 	 	$locale 	the locale to return a display variant for
378	 * @param 	[string] 	$in_locale  	optional format locale to use to display the variant name
379	 * 						If is 'null' then the default locale is used.
380	 * @return 	string  			display name of the variant for the $locale in the format
381	 * 						appropriate for $in_locale.
382     	 */
383	 function locale_get_display_variant($variant, $in_locale = null) {}
384
385
386    	/**
387	 * Checks if a $langtag  filter matches with $locale according to
388	 * RFC 4647's basic filtering algorithm
389	 *
390     	 * @param 	string 		$langtag	the language tag to check
391	 * @param 	string 		$locale		the language range to check against
392	 * @param 	bool 		$canonicalize	Canonicalize parameters?
393     	 * @return 	boolean 			'true' if $locale matches $langtag 'false' otherwise
394	 */
395    	 function locale_filter_matches($langtag, $locale, $canonicalize) {}
396
397	/**
398     	 * Searchs the items in $langtag for the best match to the language
399	 * range specified in $locale according to RFC 4647's lookup algorithm.
400	 *
401	 * @param 	array 		$langtag  	an array containing a list of language tags to compare
402	 *            					to $locale
403	 * @param 	string 		$locale   	the locale to use as the language range when matching
404	 * @param 	string 		$default  	the locale to use if no match is found
405	 * @return 	string 				closest matching language tag, $default,
406	 *						or empty string
407	 */
408    	 function locale_lookup(array $langtag, $locale, $default = null) {}
409
410
411	/**
412     	 * Returns a correctly ordered and delimited locale ID
413	 *
414	 * @param 	array 		$subtags 	an array containing a list of key-value pairs, where
415	 * 						the keys identify the particular locale ID subtags,
416	 *						and the values are the associated subtag values.
417	 *
418	 * @return 	string 				the corresponding locale identifier.
419	 */
420    	 function locale_compose_locale(array $subtags) {}
421
422
423	/**
424	 * Returns a key-value array of locale ID subtag elements.
425	 *
426	 * @param 	string		$locale		the locale to extract the subtag array from
427	 *
428	 * @return 	array 		$subtags 	an array containing a list of key-value pairs, where
429	 * 						the keys identify the particular locale ID subtags,
430	 *						and the values are the associated subtag values.
431	 */
432    	 function locale_parse_locale($locale) {}
433
434?>
435