# 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. 

{% hint style="warning" %}
:thumbsup: **You should always include the English language files in your plugin!**
{% endhint %}

## 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 :point\_right: [plugin.xml](https://devguide.e107.org/installation-and-configuration#plugin-xml),  files such as`xxxx_menu.php`or :point\_right: [addons](https://devguide.e107.org/plugin-development/extending-core-functionality-addons). |

## Defining Language Terms 

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

```php
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

:thumbsup: **Always use the format LAN\_PLUGIN\_{FOLDER}\_{TYPE} to prevent conflicts.** 

#### Avoid duplicating terms, particularly in the admin area. 

:thumbsup: 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. 

:thumbsup: Use double quotes within the defines and use `str_replace()` or :point\_right: [lanVars()](https://devguide.e107.org/classes-and-methods/parser#lanvars) for [variables ](#substitution)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.

:thumbsup: If embedding values into a phrase, use [substitution](#substitution). 

#### Avoid using [substitution](#substitution) terms which are real words or known BBCodes.

:thumbsup: Use brackets `[..]` and values such as x, y, z. See [examples ](#examples)below. 

### Examples

#### **Good**

```php
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**

```php
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**&#x20;

```php
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()`:

```php
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
```