polylang / include / api.php

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

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