PHP Class: x_class_lang

Introduction

The x_class_lang class manages language translations for a multi-language system using either a MySQL database table or a flat file. It provides methods to add, delete, and retrieve translation strings keyed by identifiers, supporting language-specific and section-specific translations. The class can load translations from a database or from a file and allows translation string substitution and extension at runtime.

Use the class by including /_framework/classes/x_class_lang.php.

Dependencies

• PHP 7.0-8.4
• PHP mysqli or compatible MySQL handler extension
• Requires an instance of a MySQL-like database class (x_class_mysql or similar) for DB operations

MySQL Table

The class uses a MySQL table to store translation entries. This table will be automatically created if missing.

Column Name	Data Type	Attributes	Description
id	int(9)	NOT NULL, AUTO_INCREMENT, PRIMARY KEY	Unique identifier for each translation entry
identificator	varchar(512)	NOT NULL	Unique key or identifier for the translation string
lang	varchar(16)	NOT NULL	Language code of the translation
translation	text		Translated text corresponding to the identifier
section	varchar(128)	DEFAULT ''	Section or context this translation belongs to
creation	datetime	DEFAULT CURRENT_TIMESTAMP	Timestamp when the entry was created
modification	datetime	DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP	Timestamp updated when the entry is modified

Key Name	Key Type	Columns	Usage
PRIMARY KEY	Primary	id	Unique identifier primary key
x_class_lang_unique	Unique	identificator, lang, section	Ensures a unique translation per identifier/language/section

Methods

---

__construct

Initializes the class for translations with MySQL or file mode.

Parameter	Type	Description	Default
$mysql	object	MySQL handler instance for DB operations	false
$table	string	Table name for storing translations	false
$lang	string	Language code to load/manage translations	"none"
$section	string	Section identifier to scope translations	"none"
$file_name	string	Optional filename to load translations from a flat file	false

Return Value	When does this occur?
int 0	If initialized with no DB operations needed

---

create_table

Creates the translation table if not existing.

Parameters	None
Return Value	boolean true on successful table creation, false otherwise

---

init

Loads all translations for the current language and section into an array for fast access.

Parameters	None
Return Value	void or false if in file mode

---

delete

Deletes a translation key from the current or specified language and section.

Parameter	Type	Description	Default
$key	string	Translation key to delete	None
$lang	string	Optional language code, defaults to loaded language	false
Return Value	boolean success or failure of deletion

---

add

Adds a new translation entry or overrides existing for the current or specified language and section.

Parameter	Type	Description	Default
$key	string	Translation key	None
$text	string	Translation text	None
$lang	string	Optional language code	false
Return Value	boolean success or failure of insert

---

translate

Retrieves the translation for a given key for the loaded language and substitutes placeholders if provided.

Parameter	Type	Description	Default
$key	string	Translation key to fetch	None
$substitution	array	null	Optional array of substitution values
Return Value	string Translated and substituted string or key if not found

---

extend

Modifies or adds a key/value pair in the loaded translation array at runtime.

Parameter	Type	Description	Default
$key	string	Translation key	None
$value	string	Translation value	None
$overwrite	boolean	Overwrite existing value if true	true
Return Value	void

---

Example

<?php
// Using MySQL instance for DB-backed translations
$db = new x_class_mysql(...);
$lang = new x_class_lang($db, 'translations', 'en', 'website');

// Add a translation
$lang->add('greeting', 'Hello, world!');

// Retrieve a translation
echo $lang->translate('greeting'); // Outputs: Hello, world!

// Substitute placeholders in translations
$lang->add('welcome_user', 'Welcome, %repsub%!');
echo $lang->translate('welcome_user', ['Alice']); // Outputs: Welcome, Alice!

// Delete a translation entry
$lang->delete('greeting');

// Extend translation dynamically
$lang->extend('farewell', 'Goodbye!', true);
echo $lang->translate('farewell'); // Outputs: Goodbye!
?>