Skip Navigation
Updated
September 19, 2023

When you install WPML, you get 65 pre-configured languages, ready to use. You can also create custom languages to display a language that’s not on the pre-configured list or is a country-specific language, such as Canadian French or British English.

On This Page:

Adding a Custom Language in the Setup Wizard

If you want to have multiple English dialects, including American English, on your site, see our guide to setting up English (US) as a custom language.

You can add a custom language as you set up WPML on your site for the first time. To add a custom language, click the Create a Custom Language link on the first step of the wizard.

Adding a custom language in the WPML setup wizard

If you are setting up a country-specific language, choose the main language from the dropdown menu and the specific country it’s for. If you’re creating a completely new language, click the Cannot find? link.

Adding a new language

Fill out the remaining fields to define your custom language. You can use one of WPML’s built in flag images or add a custom flag to display in the language switcher.

You also have the option to map your custom language to a pre-configured one to use automatic translation and spell check.

Configuring a custom language

See our section below to get the definitions and examples of each language field.

Adding a Custom Language in the Languages Settings

You can add a custom language after your site has been set up by going to WPMLLanguages. See the following video for step-by-step instructions:

To add a custom language:

  1. Go to WPMLLanguages and click on the Edit languages link.
Editing a site’s languages
  1. You will see a list of the languages on your site. Click Add languages to add a new row to your languages table.
Adding a new language
  1. Complete each field as explained in the section below, and save your new language.

If you have the Translate Everything Automatically translation mode enabled, you will see a notification to confirm you would like to translate all your site’s content into the new language.

Language Configuration Fields Defined

When adding a custom language, you need to define the following fields:

Field NameDescription
Language nameThe name you want to see in WPML’s GUI.
CodeThe name for this language in the database. Once you set this value and add content, you should never change it, otherwise content in that language will be lost. This value is used in your site’s URLs.

For example, http://wpml.org/es-mx/, http://wpml.org/?lang=fr, http://de.wpml.org.
Translation (language)The translation of the language name in the other languages on your site.
FlagAn image file with the country flag. WPML uses it in language switchers.
Default localeThe locale that will be active for this language when loading GetText translations.
Encode URLsIf your language uses a script with non-ASCII characters, such as Asian languages, Cyrillic letters, etc., encoding your URLs makes it possible for any browser and server to read and process your URL correctly.

If you choose to copy the URL from the original language for your translated pages (by going to WPMLSettingsTranslated documents options), be sure to set this to Yes.

If your language uses Latin script and ASCII characters, you do not have to encode your URLs.
hreflangThe code Google expects for this language. The language tag should contain the same information as the locale name, but in a slightly different format.

For example, if the locale for Canadian French is fr_CA, the corresponding language tag would be fr-ca. Instead of an underscore, use a dash, and ensure all letters are lowercase.
Language MappingIf your custom language is similar to an existing language, you can map the languages together. This lets you use the existing language’s spellcheck and automatic translation for your custom language.

For example, if your custom language is Swiss-German, you can map to German as the language to use for spellcheck and automatic translation.

Adding RTL (Right to Left) Support to a Custom Language

After adding a custom language that is written from right to left, you need to add RTL support for that language. This is necessary because WordPress doesn’t contain the translation files for custom languages.

Use the following steps:

  1. Go to WPML → String Translation and search for “ltr“.
  2. A drop down called Can’t find the strings you’re looking to translate? will appear. Expand it and check the box next to WordPress. Then, click on Scan translation files.
  3. Once the page reloads, click the plus icon under your custom language to translate the “ltr” string to “rtl“.
Translating the ltr string to rtl

To successfully save a custom language, make sure you see a confirmation message and no error messages. For example, you cannot add a new language that uses the code of a pre-configured language in WPML’s table, even if you do not use that language on your site.

Editing Languages Directly In the Database

WPML’s language information is kept in three tables:

  • wp_icl_languages – lists languages
  • wp_icl_languages_translations – lists language name translations
  • wp_icl_flags – indicates which image to return for the language flag

If you are manipulating the languages information, make sure that the code of the language you are adding to the database is not already used in these tables.

After adding records in these tables, we recommend saving the languages list and clearing WPML’s internal cache. To clear the cache, you need to delete the record from wp_options corresponding to option_name=’_icl_cache’ .

To keep these customizations when you update WPML, add the following piece of code to either wp-config.php or to your functions.php file in the theme folder:

define('ICL_PRESERVE_LANGUAGES_TRANSLATIONS', true);

wp_icl_languages

Each row in this table represents a different language. The table fields are as follows:

  • code – will be the language key (used in the URLs and everything else)
  • major – means that the language will be displayed at the top in the language selection panel
  • active – means that the language is selected as an active language or not
  • default_locale – locale name to be used in case the user doesn’t specify one explicitly

wp_icl_languages_translations

This table includes language name translations. It allows the language switcher to display the name of each language in the in the selected language.

  • language_code – the language we’re referencing
  • display_language_code – language that the name of the language_code is in
  • name – name for language_code in the display_language_code language

There should be a row for each combination of language_code / display_language_code for all of the site languages (including translations of every language to itself).

For every new language added, be sure to add the following to the wp_icl_languages_translations table:

  1. Translations of the new language into each of the existing site languages
  2. Translations of each existing site language into the newly added language
  3. A translation of the new language into the new language

wp_icl_flags

To display a flag for each langauge, there should be one entry in the table per language.

  • lang_code – which language the flag represents
  • flag – name of the flag image file
  • from_template – set to 1 means that the file will be loaded from the images/flags folder in the theme folder (otherwise loaded from the plugin flags folder).