polylang / include / api.php

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

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