Author诗语

Is Polylang compatible with my theme or my plugin?

Due to the huge number of themes and plugins available, it’s impossible to answer clearly to this question.
Because it uses standard WordPress functions and does not add any extra tables, Polylang is compatible, out of the box, with a lot of themes and plugins.
However, complex themes and plugins sometime require some extra work to make them multilingual ready. Fortunately, more and more developpers are testing their themes or plugins in multilingual environments.
A few very complex plugins, sometime adding extra tables, may require a lot of extra work be compatible with Polylang.
We guarantee that Polylang works with the default Twenty themes. We also included extra code to support a few very popular plugins such as Yoast SEO, some Jetpack modules, YARPP…

Synchronize metadatas between translations

Taxonomies
Comment status, Ping status, Sticky posts
Published date
Post format
Featured image
Page parent
Page template, Page order
Custom fields

Polylang offers the possibilty to synchronize some meta content and options between translations of a post or page. Note however that, whether the synchronizations are activated or not, Polylang always copies all metadatas from the source post when creating a new translation. The content can also be copied when using Polylang Pro.
Go in Languages > Settings.
All synchronizations are de-activated by default and you can activate then by checking the corresponding options in the Synchronization module. Once a synchronization option is checked, a modification to a post or page impacts all its translations.
In some cases an option may seem to have no effect.  It is indeed possible for plugins and themes to force a choice programmatically (or by using a wpml-config.xml file for the custom fields).

1.Taxonomies
Polylang handles the synchronization of the categories, tags and custom taxonomies whether they are translatable or not. A modification of your post’s taxonomies will impact all its translation.
Example with a translated taxonomy: If you choose to add the category ‘Category FR’ to a French post, Polylang will automatically add its translation ‘Category EN’ to the translated English post. It’s the same behavior if you decide to remove a category.

Individual synchronization of taxonomies: The option in Polylang settings is for all taxonomies and does not allow to activate the synchronization for some taxonomies and not for the other. Developpers can however achieve this thanks to the filter ‘pll_copy_taxonomies’.
2. Comment status, Ping status, Sticky posts
When the synchronization is activated, if you check the options comment status, ping status and sticky posts status, in your English post, your choice is automatically copied to the translated French post. Of course, if you uncheck them in your English post, they will be automatically unchecked in the French post too.

3. Published date
Example: If you assign a new published date to your English post, Polylang will automatically assign this new published date to the translated post in French. The synchronized published date is always the last entered date.

4. Post format
Example: When the post format is synchronized, if you choose to assign the Video post format to your English post, the same post format will automatically be assigned to the French translation too.

5. Featured image
Polylang handles the synchronization of the featured image whether you chose to translate media or not.
Example: When the feature image synchronization and media translation are activated, if you assign the ‘image-en’ as featured image to your English post, the translated image ‘image-fr’ would be automatically assigned as feature image for the translated post in French. If media would not be translatable, the same image would be assigned as featured image for both posts.

6. Parent page
Example: Let’s say that you have an English page ‘Parent-en’ with its French translation ‘Parent-fr’ and an English page ‘Child-en’ with its French translation ‘Child-fr’.  When the parent page synchronization is activated, assigning ‘Parent-en’ as parent of ‘Child-en’ automatically assigns its ‘Parent-fr’ as parent of ‘Child-fr’.
7. Page template, Page order
Example: If you check the synchronization option, and you choose the ‘Full-width Page Template’ for your English page, The same template is assigned to the translated French page. It’s the same behavior for the page order.

8. Custom fields
Check the Custom fields synchronization option to duplicate the same values between translations. If you modify the values of your custom fields in an English post, the same custom fields with the same values are assigned to the translated post.

Keep the custom fields synchronization option unchecked if you need to keep different custom fields or different values accross translations.

Activating the custom fields synchronization may lead to unexpected results with some third party plugins and themes storing their data as custom fields.
Individually synchronize custom fields: The option in Polylang settings is for all custom fields and does not allow to activate the synchronization for some custom fields and not for the other. Developpers can however achieve this thanks to the filter  ‘pll_copy_post_metas’ or with a wpml-config.xml file.

Working with media

1. You don’t need to translate media
2. You need to translate media
2.1 The Media Library becomes multilingual
2.2 Translate the media information
2.3 Automatically create all translations at upload
2.4 Add translated media in posts or pages
By default the Media translation module is activated. Note that, when you translate a media, the file is not duplicated. The goal of the media translation is only to translate the text (title, alternative text, description…) attached to the media.
The first question to ask yourself is: Will you need to translate the media (title, caption, alternative text, description …) or not? It is not recommended to change this setting once you started to work with media.
In some cases, you will need 2 different media for 2 different languages (for example when an image includes some text). In that case, you will use 2 different media with no need for translation. Polylang does not provide a way to create a relationship between 2 different media. In the case of 2 different headers see: Multilingual header.
1. You don’t need to translate media
If you don’t need to translate the title, alternative text and the description, deactivate the Media module in Polylang settings
Go in Languages > Settings > Media module

You will be able to work with your media library as usual, regardless the language of the posts and pages.
Note: If you already uploaded some media (while the media module was activated), they will keep their language.
2. You need to translate media
If you want to translate your media title, alternative text or description, make sure to keep the media module activated. Then Go in Media > Library.
2.1 The Media Library becomes multilingual
The language columns appear in the media list table, and you need to assign a language to all your media either by editing it or by setting the default language for the existing content.

If you don’t see all your languages, make sure that the language filter displays  “Show all languages”.
2.2 Translate the media information

Edit your media, then follow the following steps:

❶ Choose the language in the dropdown list.

❷ Fill in all the fields you need.
❸ Then save your changes.

❹ Let’s say that you want to create the French translation, click on the corresponding  in languages metabox. You will notice that Polylang automatically copies the content from the source media. Thus you need to translate only the fields that you want and keep the others common to all translations.
2.3 Automatically create all translations at upload
The default language is assigned by default to new uploaded media. Polylang Pro offers the possibility  to automatically create all translations when uploading a new media.
Go in Languages > Settings > Media module

Click on “Settings” then check “automatically duplicate media in all languages when uploading a new file” and click on “Save Changes”.

2.4 Add translated media in posts or pages
Example: If you want to add the media to a French post, Polylang filters the Media library according to the post’s language, so in French. In the screenshot below, only “Media FR” is visible in the media library, while its translation “Media EN” is hidden.

Note: Wen using the duplicating content feature of Polylang Pro, media are automatically translated when creating translation. Here “Media FR” would automatically be replaced by “Media EN” when creating the English translation.

The language switcher

Add a language switcher

Add a language switcher in a menu
Add a language switcher as a widget with legacy block
Add a language switcher as a widget in the new block editor
Add a language switcher anywhere

Options

Displays as dropdown
Displays language names and displays flags
Force link to front page
Hide the current language
Hide languages with no translation

Customizing language names
Customizing flags

Use a flag from the predefined list
Use a custom flag

Order of languages

The purpose of the language switcher is to create links to the translations of your current page. By default, if the current page is untranslated, the language switcher links to the front page in the corresponding language.
Note: To avoid 404 errors, the language switcher does not display a language on the front end if there is no published content (post or page) in that language. If there is no content in any language, then the language switcher does not appear at all.
1. Add a language switcher
1.1 Add a language switcher in a menu
You can include the Polylang language switcher in your menu. If you don’t see the language switcher metabox, check that it is not disabled in the screen options (horizontal tab which can be unfolded as shown by bullet 3 in the “Menu” documentation).
Refer to Options for the detail of what each option of the Language Switcher does.

1.2 Add a language switcher as a widget with legacy block
With Polylang you have the possibility to add our widget Language switcher, in the Appearance tab > Widgets sub-tab, by first adding a block “Legacy Widget” in which you then select the Polylang Language Switcher.
This option works with Polylang Pro for existing widgets only, it is no longer possible to add it. The block must be used instead.
Refer to Options for the detail of what each option of the Language Switcher.
You can choose to display either the language name or its flag or both
1.3 Add a language switcher as a Block in the new widgets block editor
With Polylang Pro you have the possibility to add a language switcher in the new widget block editor introduced in WordPress 5.8. To do so simply search for “Language Switcher” in the search form of the block editor in your Appearance tab > Widgets sub-tab.
Click on the icon of the block, it will add it to the main blocks list (central scroll zone) and open the block editor embedded view in witch you’ll find all the “Language Switcher” options.
Refer to Options for the detail of what each option of the Language Switcher.

1.4 Add a language switcher anywhere
You can include a language switcher anywhere in your site by using the PHP template tag pll_the_languages().
2. Options
By default the language switcher will display languages names only. You can easily change the configuration using the available options detailed below.
2.1 Displays as dropdown
Dropdown with Twenty Twenty One theme
If you choose this option for the widget, it is not possible to display flags due to html limitations. It is however possible to work around this limitation with javascript (not provided by Polylang). There is no such limitation when using this option in the menu.
2.2 Displays language names & Displays flags
In the examples below (with the Twenty Twenty One theme), you can see the result when both settings have been checked for the language switcher :

In a menu

In a widget

2.3 Forces link to front page
You have the possibility to always link to the front page in the corresponding language even if the current page is translated.
2.4 Hide the current language
Choose this option  to never display the current language.
For example, if your home page is translated in three languages (English / Italian / French). When viewing the English home page the language switcher will only display Italian and French. You then click on French (Français in the gif), the language switcher will display English and Italian as available languages to switch to.

 
2.5 Hide languages with no translation
If, for example, the current English post is not translated in Italian, the language switcher doesn’t display any link for Italian.
3. Customizing language names
You can change the language name by modifying the full name of the language.
4. Customizing flags
4.1 Use a flag from the predefined list
You can choose your language flag among all the flags when creating or editing a language. This flag is used on both frontend and admin sides.
4.2 Use a custom flag
It is possible to use your own images as flags. You have to use PNG or JPG files and name them with the WordPress locale. For example, en_GB.png. Then upload this file in the /wp-content/polylang/ directory (create the directory if it does not exist). Don’t use the /polylang/flags/ directory as your file would be removed when automatically updating the plugin.
Once the custom flag is uploaded, go in Languages > Settings > URL modifications module then click on save changes. Note that your custom flags are not used on admin side.
Developers can also access more options by using the filter pll_custom_flag
5. Order of languages
You can choose the order of the languages in the language switcher when creating or editing a language.

Multilingual Custom Post Types and Taxonomies

Go to Languages > Settings
Click on the settings link of the Custom post types and Taxonomies module. Below is an example displaying a custom post type ‘Book’ and its custom taxonomy ‘Genre’. The checkboxes allow you to choose whether to enable the languages and translation management for these post types an taxonomies.

Note: To correctly display the languages columns and metabox for custom post types and taxonomies, plugins or theme authors must use the same actions and filters as WordPress. Otherwise there is now way for Polylang to add its own interface.
Note for developpers: By default, Polylang displays the post types and taxonomies in the settings for which the parameter ‘public’ is set to true. Other won’t appear. You can use the wpml-config.xml file or the filters ‘pll_get_post_types’ and ‘pll_get_taxonomies’ to change that.

Strings translation

1. Filter
2. Translate strings
2.1 Create your translations
2.2 Widgets translations
3. Translate URL slugs
4. Cleaning the database
4.1 Cleaning the translations
4.2 Cleaning the strings generated by the WPML functions
4.3 Cleaning the strings generated by the Polylang functions
5. Information for the developpers
Only the Administrator can access to the Strings translations.
Go in Languages > Strings translations
The Strings translations list table allows you to translate strings which are generally in the themes and plugins options.  The Strings translations list table displays the strings registered by Polylang and WPML PHP functions and by the wpml-config.xml file.
Note: when you switch from WPML to Polylang thanks to the WPML to Polylang plugin, the strings translations are imported too.
Note: The strings hardcoded in PHP files are not handled by the Strings translations list table. These strings are stored in .po/.mo files and you can translate them with tools like Poedit or the Loco translate plugin.
1. Filter

You can filter the strings translation by the group. By default the filter is on “View all groups”.
WordPress group: Polylang always creates a WordPress group with 4 options: the Site title, the Tagline, the Date Format and the Time format. You can refer to the codex to choose date formats and time formats adapted to your languages.
Widget group: This group appears only once you have setup Widgets . You can translate here all the titles of your Widgets. The text of the Widget Text is also translatable.

Url slugs group: You need Polylang Pro to translate your slugs.

Other groups: Plugins and themes can add their own strings, generally filled by the user in the plugins and theme options.
There is also a search input field which allows you to search for source strings or specific strings names (the search dos not cover the translations).
2. Translate strings
2.1 Create your translations
You first need to fill in the relevant fields in the WordPress, plugins or theme settings the source strings.
Then go in the Languages > Strings translations, translate your strings in the Translations column and then click on “Save changes”. If some languages are missing, make sure that the languages filter displays “Show all languages”.

2.2 Widgets translations
If a widget title is not listed in the strings translations list table, it is most likely because the widget uses the old Widget API (WP < 2.8). Unfortunately, there is no way to make Polylang automatically compatible with all widgets which use this old API.
Widget Text: Appart from the widget titles which should all be listed, only the text of the widgets Text are displayed  in the Strings translation list table, except if other Widgets use the same filter.
Note: remember that when the text of a widget is not translatable, it is still possible to have one widget per language.
3. Translate URL slugs
Polylang Pro offers the possibility to translate the URL slugs for the category base, the tag base, the post formats, the custom post types, the custom taxonomies, the author base… To know more about this functionality, see Translate slugs with Polylang Pro.
4. Cleaning the database
4.1 Cleaning the translations

❶ Polylang stores the translations in the database (as post type ‘polylang_mo’ in the ‘wp_posts’ table to be precise). When a theme or a plugin is deactivated, the translations associated to its options are kept in the database, although these translations are not displayed anymore in the list table.
You can permanently delete these translations from your database by checking the “Clean strings translation database” option ❷ , and then clicking on “Save Changes”.

4.2 Cleaning the strings generated by the WPML functions

❸ Thanks to the WPML compatibility mode of Polylang, some strings may be registered by the WPML functions, used by the themes and plugins. Unlike strings registered by the native functions of Polylang, and to keep the functionality as close as it is in WPML, these strings are not removed from the list table when the corresponding plugin or theme is deactivated. You can permanently delete them thanks to the delete Bulk Action.
4.3 Cleaning the strings generated by the Polylang functions

❹ The checkbox is greyed for the strings generated by the Polylang functions, or wpml-config.xml files (which may be provided by your theme or plugins). These strings are automatically removed from the list when the corresponding plugin or theme is deactivated (although the translations are kept as explained above).
5. Information for the developpers
There are 3 ways to include strings in the list table, please refer to the documentation for the developpers: ‘pll_register_string’, wpml compatibility mode, wpml-config.xml.

Translating URLS slugs

This feature, available only in Polylang Pro, allows you to translate the URL slugs for post formats, custom post types, custom taxonomies, as well as category, tag, author, page, attachment… The example below is for the slug ‘category’ but translating other URL slugs works the same way.
Let’s say that you have created a category in French and its English translation. By default your categories URLs would look like:
• /fr/category/voyage
• /en/category/travel
As you can see, the slug ‘category’ is identical whatever the language.
Go in Languages > Strings translations
Notes: You can filter the strings translation by the group ‘URL slugs’. If some languages are missing, make sure that the admin languages filter displays “Show all languages”.
In the example below the string ‘category’ is translatable in French and in English. Translate the URL slugs in the Translations column, then click on “Save changes”.

Once done, your categories URLs look like:
• /fr/categorie/voyage
• /en/category/travel

Import and Export strings translations

Strings translations Import and Export module is integrated by default in Polylang Pro. The goal of this module is to export all your Strings Translations in a format (the PO format) that allows you to translate them (from the default language of your site, to a language you select). And finally to import these translated strings.
Export Strings Translations
So first, go in Languages > Strings translations.
There is a metabox at the bottom of the page that allows you to export your strings translations :

❶ You can choose the language(s) in which you want to translate the strings. You will then have a translation file for each selected target language.
❷ You can filter the strings translations to export only one group, or all of them (they are grouped by core feature, plugin, or widget). By default the filter is on “Export all groups”.
❸ Finally, click on “Download” to download your export file.
So you get a ZIP file that contains one translation file for each previously selected target language.
Now that you have your translation file(s), you can proceed to their translation through a professional translator, or use tools that allow you to translate this file format as Poedit.
Note: If you don’t want to do a translation, but only want to import your strings on another site, read Export strings translations from one site to another.
Import Strings Translations
Go in Languages > Strings translations.
There is a metabox at the bottom of the page that allows you to import your strings translations :

❶ Choose the file you want to import (it has to be a PO file like the exported format).
❷ Click on “Upload” to launch the import process.
After hitting the “Upload” button, a success message is displayed ❸ and you obtain your strings translated ❹ as shown below.

Note: You can only translate one language at a time, because we have one translation file per target language, and we only import one file at a time.
Exporting your strings translations from one site to another
When you export your strings translations, a “Site-Reference” attribute is created in the translation file, as shown here :

If you want to import this file on another site than the one from which it has been exported, you will have to change the value of “Site-Reference”.
So you have to replace the current URL by the one you want to import your strings translations on.

URL modifications

The language is set from content
The language is set from the code in the URL
The language is set from the directory name in pretty permalinks
Subdomains name and domains
Hide URL language information for default language
/language/ in pretty permalinks
The front page url contains the language code instead of the page name or page id

Go in Languages > Settings

1. The language is set from content
❶ The URL is not modified: whether Polylang is activated or not, the URL stays the same for posts, pages, categories and post tags. However the URL for the date and the author archives are modified to include the language code. It is indeed necessary to differentiate (for example) English monthly archives from German monthly archives.

2. The language is set from the code in the URL
❷ This option is checked by default if your Permalinks settings are set to Default.
For a site in English and in French, your posts URLs would look like:
• http://www.yoursite.com/?lang=en&p=2
• http://www.yoursite.com/?lang=fr&p=3

Compared to the option ❶, there are less compatibility risks with third party plugins and themes. This is due to the fact that in the case ❶, Polylang defers the language definition compared to the other cases a explained in the diagram below.

3. The language is set from the directory name in pretty permalinks
❸ This option is checked by default if your Permalinks settings are set to pretty permalinks. In most cases, you should keep this option as is, unless you know what you are doing. For a site in English and in French, your posts URLs would look like:
• http://www.yoursite.com/en/my-post/
• http://www.yoursite.com/fr/mon-article/

Note that, except with the first option which keeps as much URLs as possible, when Polylang is de-activated, every URL loose the language information and thus all external links are broken.
4. Subdomains name and domains
❹❺ For advanced users, it is possible to use subdomains (or a different domain per language). All your subdomains (or domains) must point to the same directory (where the WordPress index.php is present). Polylang checks if your domains or subdomains are correctly accessible. Otherwise, Polylang returns an error message. Contact your host provider to get the documentation for the subdomains and domains installation.
Note: we know that the interface of some host providers does not allow to choose the directory where a subdomain is pointing. Check with your host provider if it offers this possibility.
5. Hide URL language information for default language
❻ This option allows you to hide the language information only for the default language. In this case the monthly archives URL in the default language will look
like:
• http://www.yoursite.com/2015/03/

This option is very useful if you install Polylang on an existing website as none of your existing URLs in the default language are modified.
6. /language/ in pretty permalinks
❼ Here you can choose to include the keyword «language» in your URLs.
Keep /language/ in pretty permalinks: the monthly archives URL will look like:
• http://www.yoursite.com/language/en/2015/03/
Remove /language/ in pretty permalinks: the monthly archives URL will look like:
• http://www.yoursite.com/en/2015/03/

7. The front page url contains the language code instead of the page name or page id
❽ This option is available only if you chosen to display the front page as a static page in Settings > Reading. For a site in English and in French, the URLs of your home pages would look like:
• http://www.yoursite.com/en/
• http://www.yoursite.com/fr/
instead of
• http://www.yoursite.com/en/home/
• http://www.yoursite.com/fr/home-fr/

If English is your default language, you can even hide this language code /en/ by checking the option ❻. When both options ❻ and ❽ are checked, the URLs of your home pages look like:
• http://www.yoursite.com/
• http://www.yoursite.com/fr/

Detect the browser preferred language

Go in Languages > Settings
Note that this option works when the language is chosen from the content, from the directory name in the url or from the subdomain. You need Polylang Pro and SSL for it to work when you use multiple domains.

When activated, someone visiting your homepage for the first time is redirected to the homepage in the language according to his browser preferences. If his browser preferences do not include any language of your site, the default language is used.
Polylang sets a cookie for returning visitors to be redirected to the homepage in their last browsed language. Thus, if you want to test the functionality on your site, don’t forget to clear your cookies between each test.
Here are some examples with French as default language:

Case 1: None of the browser language preferences of your visitor match the website languages. The visitor is redirected to the French home page (default language). If his last browsed page is in English, he will be redirected to the English homepage at the second visit.

Cases 2 & 3: In both cases, English is the first language in the browser preferences of your visitor which matches one of your website languages. The visitor is redirected to the English home page.
Note: If you don’t want any redirection to occur, you must deactivate the browser preferred language detection and hide the default language code in URLs by checking the relevant option in the URL modifications settings.