Guide to Creating a Interface Localization for Cotonti CMS

Guide to Creating a Cotonti Interface Localization

A complete practical guide to creating a Cotonti CMF interface localization for a site developer. All three levels of language files are covered step by step: system, theme, extensions. It describes how to add a new language (for example, Georgian, Chechen, Tatar), how to override a non-standard language code without modifying the core, how to configure the site language and the user language. Tables of ISO 639-1 codes for the languages of the former USSR countries and the republics of the Russian Federation are provided, along with the file placement scheme, code examples, and a troubleshooting section. All data is based on the architecture of Cotonti V.1.

Table of Contents

1. Introduction
2. Language Codes
3. Language File Structure
4. Creating the Core Localization
5. Creating a Theme Localization
6. Creating an Extensions Localization
7. Adding a New Language
8. Overriding a Language Code
9. Configuring the Site Language
10. Troubleshooting
11. Conclusion

1. Introduction

Cotonti CMF is designed as a multilingual system. All textual interface information is stored in separate language files, which are ordinary PHP files containing arrays of language strings. The base installation includes language packs for English and Russian.

There are two fundamentally different approaches to localization:

1. Full localization — creating a new language pack from scratch. All language files are edited, and a complete translation of the interface is produced.
2. Partial override — changing individual language strings without creating a full language pack. This is recommended for modifying specific phrases in an existing localization.

Important: modifying system localization files is not recommended, as it may cause problems during system updates. For pinpoint changes, use theme localization files.

2. Language Codes

To designate languages, the system uses two-letter codes according to the ISO 3166-1 standard. Examples: en (English), ru (Russian), de (German).

The language code is used in the name of every language file: xxxx.en.lang.php, xxxx.ru.lang.php, etc.

Official Languages of the Former USSR Countries

Languages of the Republics within the Russian Federation

3. Language File Structure

Cotonti language files are divided into three types, each placed in its own directory.

System Language Files

Located in the /system/lang/{lang_code}/ directory:

Module Language Files

Located in the modules/{module_name}/lang/ directory:

modules/{module_name}/lang/{module_name}.{lang_code}.lang.php

Plugin Language Files

Located in the plugins/{plugin_name}/lang/ directory:

plugins/{plugin_name}/lang/{plugin_name}.{lang_code}.lang.php

Theme Language Files

Located in the root of the theme directory:

themes/{theme_name}/{theme_name}.{lang_code}.lang.php

4. Creating the Core Localization

Step 1. Create the Language Directory

Create a directory with the language code in /system/lang/. For example, for the Georgian language (ka):

/system/lang/ka/

Step 2. Copy the English Files

Copy all files from /system/lang/en/ into the created directory. Rename them according to the new language code:

/system/lang/ka/admin.ka.lang.php
/system/lang/ka/countries.ka.lang.php
/system/lang/ka/main.ka.lang.php
/system/lang/ka/message.ka.lang.php
/system/lang/ka/translit.ka.lang.php
/system/lang/ka/users.ka.lang.php

Step 3. Translate the Content

Open each file and translate the values of the language variables. Language files are PHP arrays of the following form:

<?php
defined('COT_CODE') or die('Wrong URL');

$L['Home'] = 'მთავარი';
$L['Users'] = 'მომხმარებლები';
$L['Login'] = 'შესვლა';

Translation rules:

• Only the value of a variable is translated; the key remains unchanged.
• Files must be encoded in UTF-8 without BOM.
• Existing keys must not be deleted or renamed.
• New keys may be added.

Step 4. Update the Language Name in the List

The system/functions.php file contains the $cot_languages array with the display names of the languages:

$cot_languages['cn'] = '中文';
$cot_languages['de'] = 'Deutsch';
$cot_languages['en'] = 'English';
$cot_languages['ru'] = 'Русский';
$cot_languages['ua'] = 'Українська';

To add the name of a new language, use the system/functions.custom.php file:

<?php
defined('COT_CODE') or die('Wrong URL');

$cot_languages['ka'] = 'ქართული';
$cot_languages['ce'] = 'Нохчийн мотт';
$cot_languages['tt'] = 'Татарча';

For this file to be loaded, the following option must be enabled in datas/config.php:

$cfg['customfuncs'] = true;

5. Creating a Theme Localization

Each theme can have its own language files, which allow overriding strings from the system localization or adding new ones.

Creating a Theme Localization File

Create a file at the following path:

themes/{theme_name}/{theme_name}.{lang_code}.lang.php

For example, for the index36 theme and the Georgian language:

themes/index36/index36.ka.lang.php

Example Content

<?php
defined('COT_CODE') or die('Wrong URL');

// Override a system string
$L['Contact'] = 'კონტაქტი';

// Add a new string for the theme
$L['theme_custom_greeting'] = 'მოგესალმებით';

Usage in Templates

In the theme's .tpl files, strings are called via the {PHP.L.key} tag:

{PHP.L.Contact}
{PHP.L.theme_custom_greeting}

Loading Order

Language files are loaded in the following order:

1. System language files
2. Theme language files
3. Plugin language files

Each subsequent file can override variables from the previous one.

6. Creating an Extensions Localization

Modules

Create a file:

modules/{module_name}/lang/{module_name}.{lang_code}.lang.php

Plugins

Create a file:

plugins/{plugin_name}/lang/{plugin_name}.{lang_code}.lang.php

Localizing the Plugin Administration Panel

The $L array is used to translate the plugin administration panel. Plugin settings strings are defined in the {plugin_name}.setup.php file and can be translated via the plugin's language file.

7. Adding a New Language

General Procedure

1. Create the language directory in /system/lang/{lang_code}/
2. Copy and translate all system language files
3. Add the language name in system/functions.custom.php
4. Create theme language files for the themes in use
5. Create extension language files for the installed modules and plugins
6. Set the language as default or allow users to select it in their profile

Setting the Default Language

In the datas/config.php file:

$cfg['defaultlang'] = 'ka'; // Georgian as the default language

User Language Selection

A registered user can select a language in their profile. The value is stored in the user_lang field of the cot_users table.

The administrator can forcibly set the language for all users in the section: Administration Panel → Configuration → Localization.

8. Overriding a Language Code

Overriding the code ua with uk

In stock Cotonti, the code ua is used for the Ukrainian language, which is not a standard ISO 639-1 code. The standard code is uk.

To override it without modifying the core, add the following to system/functions.custom.php:

<?php
defined('COT_CODE') or die('Wrong URL');

// Remove the non-standard code
unset($cot_languages['ua']);
// Add the standard code
$cot_languages['uk'] = 'Українська';

Creating a Directory for the New Code

Create the /system/lang/uk/ directory and copy the language files from /system/lang/ua/ into it.

Renaming Theme Files

If the theme language files used the code ua, rename them:

themes/{theme}/{theme}.ua.lang.php → themes/{theme}/{theme}.uk.lang.php

9. Configuring the Site Language

Main Parameters

Browser Language Detection

The cot_lang_determine() function automatically determines the user's preferred language based on the HTTP_ACCEPT_LANGUAGE header and matches it against the available language packs.

10. Troubleshooting

The language is not displayed in the list

• Check that the /system/lang/{lang_code}/ directory exists
• Make sure the language name has been added to $cot_languages via functions.custom.php
• Check whether the option $cfg['customfuncs'] = true; is enabled

The translation is not applied

• Check the file encoding (UTF-8 without BOM)
• Make sure the language variable key is specified correctly
• Check the loading order: theme files override system files

Errors after updating

• Do not edit system language files directly
• Use theme localization files to override strings
• Maintain your own functions.custom.php file for customizations

The administration panel is not translated

• The $L array in the plugin's language file is used to translate the plugin admin panel
• Make sure the localization file is placed at the correct path

11. Conclusion

Cotonti CMF localization is carried out through a system of language files consisting of three levels:

1. System level — /system/lang/{lang_code}/
2. Theme level — themes/{theme_name}/{theme_name}.{lang_code}.lang.php
3. Extensions level — modules/{module_name}/lang/ and plugins/{plugin_name}/lang/

To add a new language, you must create a complete set of language files, starting from the system level. For pinpoint changes, a theme localization file is sufficient.

Customization that does not affect the system core is done via system/functions.custom.php. This file is not overwritten during Cotonti updates, which ensures that user modifications are preserved.