Custom Wording and Translations

Customising wording works with .ini files, practically just like it works in Joomla. Essentially you add an override file per language to a specific location on the server, look up the keyword of the text you want to alter and add it to the file. See all details below.

How wording and translation is handled in ConfigBox

Texts you see on the pages handled by ConfigBox are in two files per language in ini format, we call them system language files.

On top of system language files, the system looks for custom language files that you can use to customize specific phrases or add phrases for any custom templates or views you make.

How does a language file look like?

A typical line in a language file looks like this:

On the left of the equal sign you see the keyword of the phrase the system looks for - it is (and must be) in upper case. On the right within double quotes you see the phrase that the system will display. Typically, the keyword is the uppercase form of the phrase in English.

How are the lines in language files used?

Throughout the code base you'll find calls to KText::_(). For example

This outputs "Localised Wording".

Locations of system language files

We refer to appDir for file locations. See this article for the location in your platform.

Joomla:

{appDir}/language/en-GB/frontend.ini (for phrases shown in the frontend pages or shown in both front and backend)
{appDir}/language/en-GB/backend.ini (for phrases only shown in the backend)

Locations of custom language files

We refer to customizationDir for file locations. Customizations are in a location separate to the application. See this article for the location on your platform.

{customizationDir}/language_overrides/en-GB/overrides.ini

Note: Custom language files override the system language file phrases of both frontend and backend. 

Which editor should I use to edit custom language files?

Files need to be saved as plain text with UTF-8 encoding and only use regular double quotes (like this: ") for wrapping phrases.

If you are not sure what that means, take the safe route and use one of these editors with default settings:

• Windows: Notepad++ (www.notepad-plus-plus.org)

• Mac OS X: TextWrangler (www.barebones.com/products/textwrangler)

Syntax rules and helpful notes on editing language files

• The keyword must remain unaltered and in upper case

• The translation must be wrapped in double quotes.

• Do not put line breaks in your phrases, if you need a make a line break in your phrase use <br />

• If you need a double quote in your phrase, prepend it with a backslash (e.g. \")

• Within a major release, we avoid breaking changes to phrases (as with all else). On a major release, be sure to plan in a revision of any customization.