# How to Edit Language Files in Blesta Club Extensions

*Change labels, tailor wording to your business, or translate any Blesta Club extension without editing its working code.*

Blesta Club extensions keep the text shown to staff and clients in separate language files. This means you can rename a button, clarify a help message, or translate an extension without having to change the PHP classes that make it work.

Although the exact filenames differ between extensions, the language-file structure and editing process are the same. This guide applies to Blesta Club plugins, modules, payment gateways, and other extensions that include a `language` directory.

## Finding an extension's language files

First, find the extension inside your Blesta installation. Its location depends on its type:
 

```text

plugins/extension_name/

components/modules/extension_name/

components/gateways/merchant/extension_name/

components/gateways/nonmerchant/extension_name/

```
 

Open the `language` directory within the extension. The supplied US English files will normally be under:

```text

language/en_us/

```

For example, a plugin's complete path might be:

```text

plugins/extension_name/language/en_us/

```

An extension may contain several language files. Their names normally correspond to a controller, model, settings page, widget, or the main extension class. Larger extensions have more files because their staff pages, client pages, validation messages, and settings are kept separate.

## Understanding a language entry

Open a language file in a plain-text or code editor and you will see entries similar to this:

```php

$lang['ExamplePlugin.index.submit'] = 'Save Changes';

```

The text inside the square brackets is the language key used by the extension. The text after the equals sign is the value displayed to the user.

To change **Save Changes** to **Save Settings**, edit only the value on the right:

```php

$lang['ExamplePlugin.index.submit'] = 'Save Settings';

```

Do not rename the key. If `ExamplePlugin.index.submit` is changed or removed, the extension will no longer be able to find that translation.

## Changing the supplied wording

Make a backup of the extension's language directory before editing it. Then:

1. Open the relevant file in a code editor.

2. Search for the wording you want to change.

3. Edit the value between the quotes, leaving the key and PHP syntax intact.

4. Save the file as plain text.

5. Reload the relevant page in Blesta and check the result.

The same phrase may be defined more than once. A navigation item, page title, box heading, and button can each use a different key, even when they currently display identical wording. Search all files in the language directory if you want to change a term throughout an extension.

## Adding another language

To translate an extension, copy its complete `en_us` directory and rename the copy to the language code used by your Blesta installation. Common examples include:

```text

language/en_gb/

language/de_de/

language/es_es/

language/fr_fr/

```

Translate the values in every copied file, but preserve the directory structure, filenames, and language keys. The new directory name must match the language code configured in Blesta.

Copying every file gives your translation the same structure as the supplied language and makes it much easier to compare the two after a future update.

## Handling quotes correctly

Language files are PHP files, so punctuation matters. Each entry must retain its `$lang[...] = '...';` structure.

Most values use single quotes. If your wording contains an apostrophe, escape it with a backslash:
 

```php

$lang['ExamplePlugin.index.empty'] = 'There aren\'t any results yet.';

```

Without the backslash, PHP treats the apostrophe as the end of the value and the affected page may fail to load.

Do not replace ordinary code quotes with typographic or curly quotes. A code editor will preserve the correct characters, while a word processor may silently change them.

## Preserving placeholders

Some language entries contain placeholders such as `%1$s`, `%2$s`, or `%1$d`. Blesta replaces these with a name, date, number, link, or other value when the page is displayed:

```php

$lang['ExamplePlugin.index.welcome'] = 'Welcome, %1$s';

```

You can move a placeholder to suit the grammar of your language, but do not translate, remove, or alter it. If an entry contains several placeholders, retain all of them and make sure their numbers remain correct.

Comments beside an entry may explain what each placeholder represents:

```php

$lang['ExamplePlugin.index.created'] = 'Created on %1$s'; // %1$s is the formatted date

```

## Preserving HTML

Some values include HTML for a link or simple formatting:

```php

$lang['ExamplePlugin.index.help'] = 'Read the documentation.';

```

You can translate the visible wording, but preserve required tags, attributes, quotation marks, and placeholders. Changing the markup incorrectly can break the link or the surrounding page.

Only add HTML where the extension already expects it. Some parts of Blesta escape language values before displaying them, so newly added HTML may appear as plain text.

## What not to translate

Translate the values shown to people, not the identifiers used by the extension. Leave these unchanged:

- Language keys inside `$lang[...]`

- Filenames and directory names, apart from the copied language-code directory

- Placeholders such as `%1$s`

- HTML tag and attribute names

- Internal codes, API values, and template tags

Comments beginning with `//`, `#`, or enclosed by `/* ... */` are notes for developers and are not displayed in Blesta. Translating them is optional.

## Checking your changes

After saving a language file, visit every relevant staff and client page. Check headings, buttons, tooltips, validation errors, confirmation messages, and any text containing a placeholder or link.

If a page stops loading, restore your backup and inspect the latest changes for:

- An unescaped apostrophe

- A missing opening or closing quote

- A missing square bracket

- A missing semicolon

- A damaged placeholder or HTML attribute
 

If the page loads but still shows the old wording, confirm that you edited the directory matching the active Blesta language. You may also need to clear Blesta's cache and refresh the page.

## Keeping customisations through updates

Updating an extension normally replaces the files in its directory. Changes made directly to the supplied `en_us` files may therefore be overwritten.

Keep a backup of all customised language files outside the extension directory. Before restoring them after an update, compare your copy with the files in the new release. The update may introduce new keys, change placeholders, or remove wording that is no longer used.

A separate language directory keeps a translation apart from the supplied `en_us` files, but it should still be backed up before updating. After every update, compare it with the latest `en_us` directory and translate any new entries.

If you maintain extensive wording changes, use a file comparison tool or version-control system. It will show exactly which lines changed and make upgrades much safer than copying old files over a new release without checking them.

## A quick checklist

Before uploading a customised or translated language directory, confirm that:
 

- The language directory uses the exact code configured in Blesta.

- Every original filename is present.

- All language keys remain unchanged.

- Apostrophes inside single-quoted values are escaped.

- Every placeholder from the original value is preserved.

- Required HTML remains valid.

- The files are saved as plain text.

- You have kept a backup outside the extension directory.

Language files offer a safe and flexible way to make any Blesta Club extension fit your terminology and your customers. Keep the keys and syntax intact, test the result in Blesta, and compare your custom files whenever you update the extension.