polylang / include / api.php

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

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