Internationalisation (LAN)

Introduction

Your website can be used in different languages. In order for your plugin or theme areas to be displayed in a specific language, it needs to be translated.

👍 You should always include the English language files in your plugin!

Language files

File Types

There are three types of language files that can be used in your plugin.

Language File	Usage
English_front.php	Used only for the frontend of your plugin
English_admin.php	Used only for the Admin Area of your plugin
English_global.php	Used site-wide, for example in 👉 plugin.xml, files such asxxxx_menu.phpor 👉 addons.

Defining Language Terms

Language Terms are more commonly known as LAN's. You can define LAN's by using PHP constants:

define("LAN_PLUGIN_MYPLUGIN_NAME", "Blank Plugin");
define("LAN_PLUGIN_MYPLUGIN_DIZ",  "A Blank Plugin to help you get started in plugin development. More details can be added here."); 
define("LAN_PLUGIN_MYPLUGIN_LINK", "Blank Link");

Best practices

👍 Always use the format LAN_PLUGIN_{FOLDER}_{TYPE} to prevent conflicts.

Avoid duplicating terms, particularly in the admin area.

👍 If defining terms for admin, always search lan_admin.php for existing LANs which may match what you require.

Never use HTML or URLs inside LAN definitions.

👍 Use double quotes within the defines and use str_replace() or 👉 lanVars() for variables where needed.

Avoid short language strings for common words

Examples are words such as 'and', 'to' and so on. There aren't always equivalents in other languages.

👍 If embedding values into a phrase, use substitution.

Avoid using substitution terms which are real words or known BBCodes.

👍 Use brackets [..] and values such as x, y, z. See examples below.

Examples

Good

define("LAN_XXX", "Thank you Firstname");
define("LAN_XXX", "Go to [x] to see the results."); // Good - replace [ and ] with <a href='...'> and </a> using str_replace()
define("LAN_XXX", "I want to [quote] here"); // Good - replace [ and ] with " " using str_replace()

Bad

define("LAN_XXX", "Thank you <b>Firstname</b>"); // Bad contains HTML
define("LAN_XXX", "Thank you <a href='http://somewhere.com'>Firstname</a>"); // Bad contains HTML and allows translator to modify link.

Substitution

define("LAN_EXAMPLE_01", "Update results: [x] records changed, [y] errors, [z] not changed");

$repl = array($changed, $errors, $unchanged);
$text = e107::getParser()->lanVars(LAN_EXAMPLE_01, $repl);

Loading Language Files

e107::lan()

To load a language file from a plugin folder, use e107::lan():

e107::lan('faqs');
e107::lan('faqs', true);
e107::lan('faqs', false, true);
e107::lan('faqs', true, true);

This will include the following paths:

e107_plugins/faqs/languages/English_front.php
e107_plugins/faqs/languages/English_admin.php
e107_plugins/faqs/languages/English/English_front.php
e107_plugins/faqs/languages/English/English_admin.php