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

## 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()](/classes-and-methods/parser.md#lanvars) for [variables ](/plugin-development/internationalisation.md#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](/plugin-development/internationalisation.md#substitution). 

#### Avoid using [substitution](/plugin-development/internationalisation.md#substitution) terms which are real words or known BBCodes.

:thumbsup: Use brackets `[..]` and values such as x, y, z. See [examples ](/plugin-development/internationalisation.md#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
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://devguide.e107.org/plugin-development/internationalisation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.