polylang / include / api.php

api.php in Polylang 1.7.3, at include/api.php

324 lines 9.4 KB

Raw Download Zip

1	<?php
2
3	/*
4	* template tag: displays the language switcher
5	*
6	* list of parameters accepted in $args:
7	*
8	* dropdown => displays a dropdown if set to 1, defaults to 0
9	* echo => echoes the the switcher if set to 1 (default)
10	* hide_if_empty => hides languages with no posts (or pages) if set to 1 (default)
11	* show_flags => shows flags if set to 1, defaults to 0
12	* show_names => shows languages names if set to 1 (default)
13	* display_names_as => wether to display the language name or code. valid options are 'slug' and 'name'
14	* force_home => forces linking to the home page is set to 1, defaults to 0
15	* hide_if_no_translation => hides the link if there is no translation if set to 1, defaults to 0
16	* hide_current => hides the current language if set to 1, defaults to 0
17	* post_id => if not null, link to translations of post defined by post_id, defaults to null
18	* raw => set this to true to build your own custom language switcher, defaults to 0
19	*
20	* @since 0.5
21	*
22	* @param array $args optional
23	* @return null\|string\|array null if displaying, array if raw is requested, string otherwise
24	*/
25	function pll_the_languages($args = '') {
26	global $polylang;
27	if ($polylang instanceof PLL_Frontend && !empty($polylang->links)) {
28	$switcher = new PLL_Switcher;
29	return $switcher->the_languages($polylang->links, $args);
30	}
31	return '';
32	}
33
34	/*
35	* returns the current language
36	*
37	* @since 0.8.1
38	*
39	* @param string $field optional the language field to return 'name', 'locale', defaults to 'slug'
40	* @return string the requested field for the current language
41	*/
42	function pll_current_language($field = 'slug') {
43	global $polylang;
44	return isset($polylang->curlang->$field) ? $polylang->curlang->$field : false;
45	}
46
47	/*
48	* returns the default language
49	*
50	* @since 1.0
51	*
52	* @param string $field optional the language field to return 'name', 'locale', defaults to 'slug'
53	* @return string the requested field for the default language
54	*/
55	function pll_default_language($field = 'slug') {
56	global $polylang;
57	return isset($polylang->options['default_lang']) && ($lang = $polylang->model->get_language($polylang->options['default_lang'])) && isset($lang->$field) ? $lang->$field : false;
58	}
59
60	/*
61	* among the post and its translations, returns the id of the post which is in the language represented by $slug
62	*
63	* @since 0.5
64	*
65	* @param int $post_id post id
66	* @param string $slug optional language code, defaults to current language
67	* @return int post id of the translation if exists
68	*/
69	function pll_get_post($post_id, $slug = '') {
70	global $polylang;
71	return isset($polylang) && ($slug = $slug ? $slug : pll_current_language()) ? $polylang->model->get_post($post_id, $slug) : null;
72	}
73
74	/*
75	* among the term and its translations, returns the id of the term which is in the language represented by $slug
76	*
77	* @since 0.5
78	*
79	* @param int $term_id term id
80	* @param string $slug optional language code, defaults to current language
81	* @return int term id of the translation if exists
82	*/
83	function pll_get_term($term_id, $slug = '') {
84	global $polylang;
85	return isset($polylang) && ($slug = $slug ? $slug : pll_current_language()) ? $polylang->model->get_term($term_id, $slug) : null;
86	}
87
88	/*
89	* returns the home url in the current language
90	*
91	* @since 0.8
92	*
93	* @param string $lang language code (optional on frontend)
94	* @return string
95	*/
96	function pll_home_url($lang = '') {
97	global $polylang;
98
99	if (empty($lang))
100	$lang = pll_current_language();
101
102	return isset($polylang) && !empty($polylang->links) && !empty($lang) ? $polylang->links->get_home_url($lang) : home_url('/');
103	}
104
105	/*
106	* registers a string for translation in the "strings translation" panel
107	*
108	* @since 0.6
109	*
110	* @param string $name a unique name for the string
111	* @param string $string the string to register
112	* @param string $context optional the group in which the string is registered, defaults to 'polylang'
113	* @param bool $multiline optional wether the string table should display a multiline textarea or a single line input, defaults to single line
114	*/
115	function pll_register_string($name, $string, $context = 'polylang', $multiline = false) {
116	global $polylang;
117	if ($polylang instanceof PLL_Admin)
118	PLL_Admin_Strings::register_string($name, $string, $context, $multiline);
119	}
120
121	/*
122	* translates a string (previously registered with pll_register_string)
123	*
124	* @since 0.6
125	*
126	* @param string $string the string to translate
127	* @return string the string translation in the current language
128	*/
129	function pll__($string) {
130	static $cache; // cache object to avoid translating the same string several times
131
132	if (!did_action('pll_language_defined')) // no need for translation
133	return $string;
134
135	if (empty($cache))
136	$cache = new PLL_Cache();
137
138	if (false === $str = $cache->get($string)) {
139	$str = __($string, 'pll_string');
140	$cache->set($string, $str);
141	}
142
143	return $str;
144	}
145
146	/*
147	* echoes a translated string (previously registered with pll_register_string)
148	*
149	* @since 0.6
150	*
151	* @param string $string the string to translate
152	*/
153	function pll_e($string) {
154	echo pll__($string, 'pll_string');
155	}
156
157	/*
158	* translates a string (previously registered with pll_register_string)
159	*
160	* @since 1.5.4
161	*
162	* @param string $string the string to translate
163	* @param string $lang language code
164	* @return string the string translation in the requested language
165	*/
166	function pll_translate_string($string, $lang) {
167	if (pll_current_language() == $lang)
168	return pll__($string);
169
170	static $cache; // cache object to avoid loading the same translations object several times
171
172	if (empty($cache))
173	$cache = new PLL_Cache();
174
175	if (false === $mo = $cache->get($lang)) {
176	$mo = new PLL_MO();
177	$mo->import_from_db($GLOBALS['polylang']->model->get_language($lang));
178	$cache->set($lang, $mo);
179	}
180
181	return $mo->translate($string);
182	}
183
184	/*
185	* returns true if Polylang manages languages and translations for this post type
186	*
187	* @since 1.0.1
188	*
189	* @param string post type name
190	* @return bool
191	*/
192	function pll_is_translated_post_type($post_type) {
193	global $polylang;
194	return isset($polylang) && $polylang->model->is_translated_post_type($post_type);
195	}
196
197	/*
198	* returns true if Polylang manages languages and translations for this taxonomy
199	*
200	* @since 1.0.1
201	*
202	* @param string taxonomy name
203	* @return bool
204	*/
205	function pll_is_translated_taxonomy($tax) {
206	global $polylang;
207	return isset($polylang) && $polylang->model->is_translated_taxonomy($tax);
208	}
209
210	/*
211	* returns the list of available languages
212	*
213	* list of parameters accepted in $args:
214	*
215	* hide_empty => hides languages with no posts if set to true (defaults to false)
216	* fields => return only that field if set (see PLL_Language for a list of fields)
217	*
218	* @since 1.5
219	*
220	* @param array $args list of parameters
221	* @return array
222	*/
223	function pll_languages_list($args = array()) {
224	global $polylang;
225	$args = wp_parse_args($args, array('fields' => 'slug'));
226	return isset($polylang) ? $polylang->model->get_languages_list($args) : false;
227	}
228
229	/*
230	* set the post language
231	*
232	* @since 1.5
233	*
234	* @param int $post_id post id
235	* @param string $lang language code
236	*/
237	function pll_set_post_language($id, $lang) {
238	global $polylang;
239	if (isset($polylang))
240	$polylang->model->set_post_language($id, $lang);
241	}
242
243	/*
244	* set the term language
245	*
246	* @since 1.5
247	*
248	* @param int $id term id
249	* @param string $lang language code
250	*/
251	function pll_set_term_language($id, $lang) {
252	global $polylang;
253	if (isset($polylang))
254	$polylang->model->set_term_language($id, $lang);
255	}
256
257	/*
258	* save posts translations
259	*
260	* @since 1.5
261	*
262	* @param array $arr an associative array of translations with language code as key and post id as value
263	*/
264	function pll_save_post_translations($arr) {
265	global $polylang;
266	if (isset($polylang))
267	$polylang->model->save_translations('post', reset($arr), $arr);
268	}
269
270	/*
271	* save terms translations
272	*
273	* @since 1.5
274	*
275	* @param array $arr an associative array of translations with language code as key and term id as value
276	*/
277	function pll_save_term_translations($arr) {
278	global $polylang;
279	if (isset($polylang))
280	$polylang->model->save_translations('term', reset($arr), $arr);
281	}
282
283	/*
284	* returns the post language
285	*
286	* @since 1.5.4
287	*
288	* @param int $post_id
289	* @param string $field optional the language field to return 'name', 'locale', defaults to 'slug'
290	* @return bool\|string the requested field for the post language, false if no language is associated to that post
291	*/
292	function pll_get_post_language($post_id, $field = 'slug') {
293	global $polylang;
294	return isset($polylang) && ($lang = $polylang->model->get_post_language($post_id)) ? $lang->$field : false;
295	}
296
297	/*
298	* returns the term language
299	*
300	* @since 1.5.4
301	*
302	* @param int $term_id
303	* @param string $field optional the language field to return 'name', 'locale', defaults to 'slug'
304	* @return bool\|string the requested field for the term language, false if no language is associated to that term
305	*/
306	function pll_get_term_language($term_id, $field = 'slug') {
307	global $polylang;
308	return isset($polylang) && ($lang = $polylang->model->get_term_language($term_id)) ? $lang->$field : false;
309	}
310
311	/*
312	* count posts in a language
313	*
314	* @since 1.5
315	*
316	* @param string $lang language code
317	* @param array $args (accepted keys: post_type, m, year, monthnum, day, author, author_name, post_format)
318	* @return int posts count
319	*/
320	function pll_count_posts($lang, $args = array()) {
321	global $polylang;
322	return isset($polylang) ? $polylang->model->count_posts($polylang->model->get_language($lang), $args) : false;
323	}
324