Localization (multilingualism) of Extra-fields. Instruction manual

Extrafields in Cotonti: a complete guide to creating and localizing values

Cotonti is a powerful and flexible open-source CMS that allows you to extend functionality almost without limits thanks to the “extrafields” system. Extrafields are custom fields that can be added to any database tables: users, pages, products, comments, etc. This makes it possible to store additional information without modifying table structures or writing complex queries.

However, simply adding a field is not enough. To create a user-friendly interface and support multilingual functionality, it is necessary to properly organize localization for both field names and their values (for example, for dropdowns or radio buttons). In this article, we will подробно explore how extrafields work in Cotonti, how to create them, and most importantly, how to correctly translate values so that your site is understandable to users in any language.

Theoretical part: architecture and extrafields API

1. Table cot_extra_fields

All extrafield settings are stored in the centralized table cot_extra_fields. The main fields of this table are:

• field_location — the name of the target table (for example, cot_users, cot_pages, cot_market).
• field_name — unique field name (Latin characters only, no spaces).
• field_type — field type (input, textarea, select, radio, checkbox, datetime, country, file, checklistbox, range, currency, double, etc.).
• field_html — HTML template for rendering the field (can be left empty, default template will be used).
• field_variants — value options for select, radio, checklistbox (comma-separated).
• field_params — additional parameters (range limits, allowed file extensions, date format, etc.).
• field_default — default value.
• field_required — whether the field is required (0/1).
• field_enabled — whether the field is enabled (0/1).
• field_parse — content parsing type (HTML, Text, etc.).
• field_description — short description (for the administrator).

Extrafields are cached, so after making changes to the table you need to clear the cache (this usually happens automatically when editing via the admin panel).

2. API functions for working with extrafields

Cotonti provides a set of functions for convenient creation, import, rendering, and processing of extrafields.

2.1. Adding a field

function cot_extrafield_add($location, $name, $type, $html = '', $variants = '', $default = '', $required = false,
 $parse='HTML', $description='', $params = '', $enabled = 1, $noalter = false, $customtype = '')

This function adds a record to cot_extra_fields and, if $noalter = false, creates a corresponding column in the target table.

Example usage “under the hood” (no need to touch the code):

cot_extrafield_add('cot_market', 'product_status', 'select',
 '', 'unknown,instock,outofstock,ending,onorder', 'unknown', 0,
 'HTML', 'Availability status', '', 1);

2.2. Building the HTML element

cot_build_extrafields($name, $extrafield, $data) — returns ready HTML code of the field (input, select, etc.) for use in forms.

2.3. Importing data from a form

cot_import_extrafields($inputname, $extrafield, $source = 'P', $oldvalue = '', $titlePrefix = '') — processes incoming data, applies validation, checks required fields, and handles file uploads.

2.4. Preparing value for output

cot_build_extrafields_data($name, $extrafield, $value, $parser = '') — prepares the field value for display on the site. For select, radio, checklistbox types, this function automatically attempts to find a translation in the language array.

2.5. Getting the field title

cot_extrafield_title($extrafield, $titlePrefix = '') — returns a localized field name by checking keys $L['location_name_title'], $L['name_title'], and field_description.

3. Field types and their features

Let’s look at the main extrafield types:

• input — standard text field.
• inputint — integer number.
• currency, double — floating point numbers.
• textarea — multi-line field.
• select — dropdown list.
• radio — radio button group.
• checkbox — single checkbox.
• datetime — date and time picker.
• country — list of countries.
• file — file upload.
• checklistbox — checkbox group (multiple selection).
• range — numeric range selection.

Each type has corresponding build and validation methods in the API.

Localization of extrafield values

1. Localization principle in Cotonti

In Cotonti, language strings are stored in the global array $L. They can be defined in module files, themes, or common language files. For extrafields, the following convention is used:

• Field title: $L['location_name_title'] or $L['name_title']. If neither key is found, field_description is used.
• Values for select/radio/checklistbox: $L['name_value'], where name is the field name and value is a specific value from field_variants.

For example, for the field product_status with values instock, outofstock, you need to define:

$L['product_status_instock'] = 'In stock';
$L['product_status_outofstock'] = 'Out of stock';

This is the exact format expected by cot_build_extrafields_data when displaying values.

2. Where to place language strings

Language files can be located in different places, and load priority affects which strings are used. It is generally recommended to place translations for extrafields in the language file of the module to which the field belongs. For example, for the “market” module — in modules/market/lang/ru/ru.market.lang.php.

If you are using extrafields in custom development and do not want to modify the core or modules, you can add strings to the theme language file: themes/your_theme/your_theme.ru.lang.php. This file loads later and can override module strings.

Important: if the theme language is not defined, Cotonti loads the default language (usually English).

3. Practical example: “Product status” field

Suppose we created an extrafield product_status of type select for the table cot_market. In cot_extra_fields it is configured as follows:

• field_name = product_status
• field_type = select
• field_variants = unknown,instock,outofstock,ending,onorder
• field_default = unknown
• field_description = Product availability status

For correct display in Russian, the language file should define:

$L['product_status_unknown'] = 'Not specified';
$L['product_status_instock'] = 'In stock';
$L['product_status_outofstock'] = 'Out of stock';
$L['product_status_ending'] = 'Ending soon';
$L['product_status_onorder'] = 'On order';

The product page template uses the tag {MARKET_PRODUCT_STATUS}. When rendering, Cotonti calls cot_build_extrafields_data, detects type select, checks for $L['product_status_'.$value], and substitutes the translation. If no translation is found, the raw value (e.g., “instock”) is displayed.

The tag {MARKET_PRODUCT_STATUS_TITLE} is also available, which outputs the localized field title. It is generated by cot_extrafield_title and can be overridden via $L['market_product_status_title'] or $L['product_status_title'].

4. Localization for other field types

• radio — same as select.
• checklistbox — values are stored as a comma-separated string. On output, each value is translated separately and then joined (comma by default, can be changed via field_params).
• country — built-in country name translations from $cot_countries.
• checkbox — usually displayed as 0/1, but can be manually localized via $L['fieldname_checked'] and $L['fieldname_unchecked'] in templates.

5. Prefixes in keys

Sometimes it is useful to add a prefix to localization keys to avoid conflicts. For example, in the “market” module you can use $L['market_product_status_instock']. For this, the $titlePrefix parameter of cot_import_extrafields is used. When outputting titles, cot_extrafield_title checks prefixed keys, but value output does not. Values are always looked up as $L['fieldname_value'] without prefix.

Therefore, if you want to localize values with a prefix, you still need to define keys without the prefix or modify the output function (not recommended).

Practical part: step-by-step creation and localization

Let’s go through the full cycle of creating an extrafield for the “market” module and localizing it.

Step 1. Creating an extrafield

Through the admin panel (Modules → Extrafields), add a new field:

• Table: cot_market
• Field name: product_status
• Type: select
• Variants: unknown,instock,outofstock,ending,onorder
• Default: unknown
• Required: no
• Description: Product availability status
• Enabled: yes

After saving, Cotonti will automatically create the column fieldmrkt_product_status in the table cot_market.

Step 2. Adding language strings

Open the market module language file: modules/market/lang/ru/ru.market.lang.php. Add:

$L['product_status_unknown'] = 'Not specified';
$L['product_status_instock'] = 'In stock';
$L['product_status_outofstock'] = 'Out of stock';
$L['product_status_ending'] = 'Ending soon';
$L['product_status_onorder'] = 'On order';
// If you want to localize the field title:
$L['market_product_status_title'] = 'Availability status';

If the module does not have its own language file, you can place these in a global language file or the theme language file.

Step 3. Using in the template

In the product template (e.g., market.tpl):

<!-- IF {MARKET_PRODUCT_STATUS} -->
<div class="product-status">
 <span class="label">{MARKET_PRODUCT_STATUS_TITLE}:</span>
 <span class="value">{MARKET_PRODUCT_STATUS}</span>
</div>
<!-- ENDIF -->

If the database value is outofstock, the page will display:
Availability status: Out of stock

Localization of extrafield titles

To translate the field title ({MARKET_PRODUCT_STATUS_TITLE}), use:

1. With table prefix:
   $L['market_product_status_title']
2. Without prefix:
   $L['product_status_title']

The first takes priority; otherwise the second is used; if neither exists, field_description is used.

Examples for different languages

Russian (ru):

$L['market_product_status_title'] = 'Статус наличия';
// or
$L['product_status_title'] = 'Статус наличия';

English (en):

$L['market_product_status_title'] = 'Availability status';
// or
$L['product_status_title'] = 'Availability status';

Polish (pl):

$L['market_product_status_title'] = 'Stan dostępności';
// or
$L['product_status_title'] = 'Stan dostępności';

Ukrainian (uk):

$L['market_product_status_title'] = 'Статус наявності';
// or
$L['product_status_title'] = 'Статус наявності';

Where to place

Add these to the module language file or your theme language file. Don’t forget to clear the cache afterward.

Step 4. Cache clearing

After adding language strings, clear both language cache and extrafields cache via the admin panel or manually.

Step 5. Example for English version

Create en.market.lang.php:

$L['product_status_unknown'] = 'Unknown';
$L['product_status_instock'] = 'In stock';
$L['product_status_outofstock'] = 'Out of stock';
$L['product_status_ending'] = 'Ending soon';
$L['product_status_onorder'] = 'On order';
$L['market_product_status_title'] = 'Availability status';

Switching the site language will automatically change displayed values.

Step 6. Handling multiple selection (checklistbox)

If the field type is checklistbox, values are stored like "instock,ending". On output, cot_build_extrafields_data splits, translates each, and joins them back.

Advanced features and pitfalls

1. Using field_params

This parameter allows fine-tuning:

• datetime — min,max,format
• file — upload directory
• range — min/max values
• checklistbox — output separator

2. Language file priority

Load order:

1. lang/ru/main.ru.lang.php
2. modules/*/lang/ru/ru.*.lang.php
3. plugins/*/lang/ru/ru.*.lang.php
4. themes/theme/theme.ru.lang.php

Later files override earlier ones.

3. Case sensitivity

Keys are case-sensitive. Use lowercase for consistency.

4. Extrafields caching

Data is cached. If modifying DB manually, clear cache via Cot::$cache->db->remove('cot_extrafields', 'system').

5. Version compatibility

API is mostly identical across Cotonti versions.

6. Common mistakes

Keys like $L['market_product_status_instock'] will NOT work for values. Use $L['product_status_instock'].

Also verify language file loading and cache clearing.

Conclusion

Extrafields in Cotonti are a powerful tool for building flexible websites. Proper localization ensures a user-friendly multilingual interface. The key rule is naming: $L['fieldname_value'].

In this article, we covered:

• extrafield architecture and API;
• localization methods;
• a practical “Product status” example;
• common mistakes and solutions.

Using this knowledge, you can easily extend any module and properly localize it. Always remember caching, file priority, and testing.