polylang / include / api.php

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

424 lines 11.9 KB

Raw Download Zip

1	<?php
2	/**
3	* @package Polylang
4	*/
5
6	/**
7	* Template tag: displays the language switcher
8	*
9	* List of parameters accepted in $args:
10	*
11	* - dropdown => displays a dropdown if set to 1, defaults to 0
12	* - echo => echoes the switcher if set to 1 ( default )
13	* - hide_if_empty => hides languages with no posts ( or pages ) if set to 1 ( default )
14	* - show_flags => shows flags if set to 1, defaults to 0
15	* - show_names => shows languages names if set to 1 ( default )
16	* - display_names_as => whether to display the language name or its slug, valid options are 'slug' and 'name',
17	* defaults to name
18	* - force_home => forces linking to the home page is set to 1, defaults to 0
19	* - hide_if_no_translation => hides the link if there is no translation if set to 1, defaults to 0
20	* - hide_current => hides the current language if set to 1, defaults to 0
21	* - post_id => if not null, link to translations of post defined by post_id, defaults to null
22	* - raw => set this to true to build your own custom language switcher, defaults to 0
23	* - item_spacing => whether to preserve or discard whitespace between list items, valid options are
24	* 'preserve' and 'discard', defaults to preserve
25	*
26	* @api
27	* @since 0.5
28	*
29	* @param array $args optional
30	* @return null\|string\|array null if displaying, array if raw is requested, string otherwise
31	*/
32	function pll_the_languages( $args = '' ) {
33	if ( PLL() instanceof PLL_Frontend ) {
34	$switcher = new PLL_Switcher();
35	return $switcher->the_languages( PLL()->links, $args );
36	}
37	return '';
38	}
39
40	/**
41	* Returns the current language on frontend
42	* Returns the language set in admin language filter on backend ( false if set to all languages )
43	*
44	* @api
45	* @since 0.8.1
46	*
47	* @param string $field Optional, the language field to return ( see PLL_Language ), defaults to 'slug', pass OBJECT constant to get the language object.
48	* @return string\|PLL_Language\|bool The requested field for the current language
49	*/
50	function pll_current_language( $field = 'slug' ) {
51	if ( OBJECT === $field ) {
52	return PLL()->curlang;
53	}
54	return isset( PLL()->curlang->$field ) ? PLL()->curlang->$field : false;
55	}
56
57	/**
58	* Returns the default language
59	*
60	* @api
61	* @since 1.0
62	*
63	* @param string $field Optional, the language field to return ( see PLL_Language ), defaults to 'slug', pass OBJECT constant to get the language object.
64	* @return string\|PLL_Language\|bool The requested field for the default language
65	*/
66	function pll_default_language( $field = 'slug' ) {
67	if ( isset( PLL()->options['default_lang'] ) ) {
68	$lang = PLL()->model->get_language( PLL()->options['default_lang'] );
69	if ( $lang ) {
70	if ( OBJECT === $field ) {
71	return $lang;
72	}
73	return isset( $lang->$field ) ? $lang->$field : false;
74	}
75	}
76	return false;
77	}
78
79	/**
80	* Among the post and its translations, returns the id of the post which is in the language represented by $slug
81	*
82	* @api
83	* @since 0.5
84	*
85	* @param int $post_id post id
86	* @param string $slug optional language code, defaults to current language
87	* @return int\|false\|null post id of the translation if exists, false otherwise, null if the current language is not defined yet
88	*/
89	function pll_get_post( $post_id, $slug = '' ) {
90	return ( $slug = $slug ? $slug : pll_current_language() ) ? PLL()->model->post->get( $post_id, $slug ) : null;
91	}
92
93	/**
94	* Among the term and its translations, returns the id of the term which is in the language represented by $slug
95	*
96	* @api
97	* @since 0.5
98	*
99	* @param int $term_id term id
100	* @param string $slug optional language code, defaults to current language
101	* @return int\|false\|null term id of the translation if exists, false otherwise, null if the current language is not defined yet
102	*/
103	function pll_get_term( $term_id, $slug = '' ) {
104	return ( $slug = $slug ? $slug : pll_current_language() ) ? PLL()->model->term->get( $term_id, $slug ) : null;
105	}
106
107	/**
108	* Returns the home url in the current language
109	*
110	* @api
111	* @since 0.8
112	*
113	* @param string $lang language code ( optional on frontend )
114	* @return string
115	*/
116	function pll_home_url( $lang = '' ) {
117	if ( empty( $lang ) ) {
118	$lang = pll_current_language();
119	}
120
121	return empty( $lang ) ? home_url( '/' ) : PLL()->links->get_home_url( $lang );
122	}
123
124	/**
125	* Registers a string for translation in the "strings translation" panel
126	*
127	* @api
128	* @since 0.6
129	*
130	* @param string $name a unique name for the string
131	* @param string $string the string to register
132	* @param string $context optional the group in which the string is registered, defaults to 'polylang'
133	* @param bool $multiline optional whether the string table should display a multiline textarea or a single line input, defaults to single line
134	*/
135	function pll_register_string( $name, $string, $context = 'Polylang', $multiline = false ) {
136	if ( PLL() instanceof PLL_Admin_Base ) {
137	PLL_Admin_Strings::register_string( $name, $string, $context, $multiline );
138	}
139	}
140
141	/**
142	* Translates a string ( previously registered with pll_register_string )
143	*
144	* @api
145	* @since 0.6
146	*
147	* @param string $string the string to translate
148	* @return string the string translation in the current language
149	*/
150	function pll__( $string ) {
151	return is_scalar( $string ) ? __( $string, 'pll_string' ) : $string; // PHPCS:ignore WordPress.WP.I18n
152	}
153
154	/**
155	* Translates a string ( previously registered with pll_register_string ) and escapes it for safe use in HTML output.
156	*
157	* @api
158	* @since 2.1
159	*
160	* @param string $string the string to translate
161	* @return string translation in the current language
162	*/
163	function pll_esc_html__( $string ) {
164	return esc_html( pll__( $string ) );
165	}
166
167	/**
168	* Translates a string ( previously registered with pll_register_string ) and escapes it for safe use in HTML attributes.
169	*
170	* @api
171	* @since 2.1
172	*
173	* @param string $string The string to translate
174	* @return string
175	*/
176	function pll_esc_attr__( $string ) {
177	return esc_attr( pll__( $string ) );
178	}
179
180	/**
181	* Echoes a translated string ( previously registered with pll_register_string )
182	* It is an equivalent of _e() and is not escaped.
183	*
184	* @api
185	* @since 0.6
186	*
187	* @param string $string The string to translate
188	*/
189	function pll_e( $string ) {
190	echo pll__( $string ); // phpcs:ignore
191	}
192
193	/**
194	* Echoes a translated string ( previously registered with pll_register_string ) and escapes it for safe use in HTML output.
195	*
196	* @api
197	* @since 2.1
198	*
199	* @param string $string The string to translate
200	*/
201	function pll_esc_html_e( $string ) {
202	echo pll_esc_html__( $string ); // phpcs:ignore WordPress.Security.EscapeOutput
203	}
204
205	/**
206	* Echoes a translated a string ( previously registered with pll_register_string ) and escapes it for safe use in HTML attributes.
207	*
208	* @api
209	* @since 2.1
210	*
211	* @param string $string The string to translate
212	*/
213	function pll_esc_attr_e( $string ) {
214	echo pll_esc_attr__( $string ); // phpcs:ignore WordPress.Security.EscapeOutput
215	}
216
217	/**
218	* Translates a string ( previously registered with pll_register_string )
219	*
220	* @api
221	* @since 1.5.4
222	*
223	* @param string $string the string to translate
224	* @param string $lang language code
225	* @return string the string translation in the requested language
226	*/
227	function pll_translate_string( $string, $lang ) {
228	if ( PLL() instanceof PLL_Frontend && pll_current_language() == $lang ) {
229	return pll__( $string );
230	}
231
232	if ( ! is_scalar( $string ) ) {
233	return $string;
234	}
235
236	static $cache; // Cache object to avoid loading the same translations object several times
237
238	if ( empty( $cache ) ) {
239	$cache = new PLL_Cache();
240	}
241
242	if ( false === $mo = $cache->get( $lang ) ) {
243	$mo = new PLL_MO();
244	$mo->import_from_db( PLL()->model->get_language( $lang ) );
245	$cache->set( $lang, $mo );
246	}
247
248	return $mo->translate( $string );
249	}
250
251	/**
252	* Returns true if Polylang manages languages and translations for this post type
253	*
254	* @api
255	* @since 1.0.1
256	*
257	* @param string $post_type Post type name
258	* @return bool
259	*/
260	function pll_is_translated_post_type( $post_type ) {
261	return PLL()->model->is_translated_post_type( $post_type );
262	}
263
264	/**
265	* Returns true if Polylang manages languages and translations for this taxonomy
266	*
267	* @api
268	* @since 1.0.1
269	*
270	* @param string $tax Taxonomy name
271	* @return bool
272	*/
273	function pll_is_translated_taxonomy( $tax ) {
274	return PLL()->model->is_translated_taxonomy( $tax );
275	}
276
277	/**
278	* Returns the list of available languages
279	*
280	* List of parameters accepted in $args:
281	*
282	* hide_empty => hides languages with no posts if set to true ( defaults to false )
283	* fields => return only that field if set ( see PLL_Language for a list of fields )
284	*
285	* @api
286	* @since 1.5
287	*
288	* @param array $args list of parameters
289	* @return array
290	*/
291	function pll_languages_list( $args = array() ) {
292	$args = wp_parse_args( $args, array( 'fields' => 'slug' ) );
293	return PLL()->model->get_languages_list( $args );
294	}
295
296	/**
297	* Set the post language
298	*
299	* @api
300	* @since 1.5
301	*
302	* @param int $id post id
303	* @param string $lang language code
304	*/
305	function pll_set_post_language( $id, $lang ) {
306	PLL()->model->post->set_language( $id, $lang );
307	}
308
309	/**
310	* Set the term language
311	*
312	* @api
313	* @since 1.5
314	*
315	* @param int $id term id
316	* @param string $lang language code
317	*/
318	function pll_set_term_language( $id, $lang ) {
319	PLL()->model->term->set_language( $id, $lang );
320	}
321
322	/**
323	* Save posts translations
324	*
325	* @api
326	* @since 1.5
327	*
328	* @param array $arr an associative array of translations with language code as key and post id as value
329	*/
330	function pll_save_post_translations( $arr ) {
331	PLL()->model->post->save_translations( reset( $arr ), $arr );
332	}
333
334	/**
335	* Save terms translations
336	*
337	* @api
338	* @since 1.5
339	*
340	* @param array $arr an associative array of translations with language code as key and term id as value
341	*/
342	function pll_save_term_translations( $arr ) {
343	PLL()->model->term->save_translations( reset( $arr ), $arr );
344	}
345
346	/**
347	* Returns the post language
348	*
349	* @api
350	* @since 1.5.4
351	*
352	* @param int $post_id
353	* @param string $field Optional, the language field to return ( see PLL_Language ), defaults to 'slug'
354	* @return bool\|string The requested field for the post language, false if no language is associated to that post
355	*/
356	function pll_get_post_language( $post_id, $field = 'slug' ) {
357	return ( $lang = PLL()->model->post->get_language( $post_id ) ) ? $lang->$field : false;
358	}
359
360	/**
361	* Returns the term language
362	*
363	* @api
364	* @since 1.5.4
365	*
366	* @param int $term_id
367	* @param string $field Optional, the language field to return ( see PLL_Language ), defaults to 'slug'
368	* @return bool\|string The requested field for the term language, false if no language is associated to that term
369	*/
370	function pll_get_term_language( $term_id, $field = 'slug' ) {
371	return ( $lang = PLL()->model->term->get_language( $term_id ) ) ? $lang->$field : false;
372	}
373
374	/**
375	* Returns an array of translations of a post
376	*
377	* @api
378	* @since 1.8
379	*
380	* @param int $post_id
381	* @return array an associative array of translations with language code as key and translation post_id as value
382	*/
383	function pll_get_post_translations( $post_id ) {
384	return PLL()->model->post->get_translations( $post_id );
385	}
386
387	/**
388	* Returns an array of translations of a term
389	*
390	* @api
391	* @since 1.8
392	*
393	* @param int $term_id
394	* @return array an associative array of translations with language code as key and translation term_id as value
395	*/
396	function pll_get_term_translations( $term_id ) {
397	return PLL()->model->term->get_translations( $term_id );
398	}
399
400	/**
401	* Count posts in a language
402	*
403	* @api
404	* @since 1.5
405	*
406	* @param string $lang Language code.
407	* @param array $args WP_Query arguments ( accepted keys: post_type, m, year, monthnum, day, author, author_name, post_format, post_status ).
408	* @return int Posts count.
409	*/
410	function pll_count_posts( $lang, $args = array() ) {
411	return PLL()->model->count_posts( PLL()->model->get_language( $lang ), $args );
412	}
413
414	/**
415	* Allows to access the Polylang instance
416	* It is always preferable to use API functions
417	* Internal methods may be changed without prior notice
418	*
419	* @since 1.8
420	*/
421	function PLL() { // PHPCS:ignore WordPress.NamingConventions.ValidFunctionName
422	return $GLOBALS['polylang'];
423	}
424