Internationalization (i18n)

Relevant source files

The following files were used as context for generating this wiki page:

• apps/translations.json
• iite/overview.php
• apps/pages.php
• themes/css/iite.css
• index.php
• login.php
• apps/js/iite_components.js

The internationalization (i18n) system for this website is a server-side PHP implementation designed to deliver content in multiple languages. It primarily relies on PHP sessions to manage the user's selected language and uses a URL parameter to switch between languages. The core logic is replicated across various page-level PHP files, which pull translations from a central JSON file for UI text and a PHP array for page titles.

The system supports four languages: Italian (it), English (en), French (fr), and Spanish (es), with Italian (it) serving as the default. The implementation is consistent across the site, ensuring a uniform experience for language selection and content display.

Architecture Overview

The i18n architecture is composed of three main parts: language state management, translation data sources, and a rendering function. When a user requests a page, the server-side PHP script checks the session for a stored language preference. If none is found, it defaults to Italian. A global t() function is then used throughout the page templates to fetch the correct string for the active language from the data sources.

The following diagram illustrates the high-level flow of selecting a language and rendering a translated page.

Sources: iite/overview.php:4-9, iite/overview.php:14-18, index.php:4-13

Language State Management

Language selection is persisted across requests using PHP's $_SESSION. The active language is determined at the beginning of each page script's execution.

Setting and Persisting Language

1. Via URL Parameter: A user can change the language by navigating to a URL with a lang query parameter (e.g., /iite/overview.php?lang=en).
2. Session Update: The PHP script on the requested page detects $_GET['lang'].
3. State Persistence: The value is stored in $_SESSION['lang'].
4. Redirect: The script then performs a 302 redirect to the same URL without the query parameter to provide a clean URL to the user.
5. Default Language: If a user arrives without a lang parameter and $_SESSION['lang'] is not set, the language defaults to 'it'.

// Example from iite/overview.php
session_start();

if (isset($_GET['lang'])) {
    $_SESSION['lang'] = $_GET['lang'];
    $cleanUrl = strtok($_SERVER["REQUEST_URI"], '?');
    header("Location: $cleanUrl");
    exit;
}

$lang = $_SESSION['lang'] ?? 'it';

Sources: iite/overview.php:2-11, index.php:2-10, login.php:2-9

The sequence diagram below shows this interaction.

Sources: iite/overview.php:4-9, index.php:4-8

Translation Sources

Translations are managed in two separate files based on their purpose: general UI text and page-specific titles.

UI Text (apps/translations.json)

This JSON file is the primary source for all translatable strings within the application's UI, such as button labels, quotes, descriptions, and navigation items. It uses a nested object structure where top-level keys represent a specific UI element, and their values are objects containing language codes (it, en, fr, es) mapped to the translated string.

Structure Example:

{
  "hero_quote": {
    "it": "La mente è il codice sorgente dell’umanità.\nL’istruzione è il linguaggio con cui lo riscriviamo.",
    "en": "The mind is humanity’s source code.\nEducation is the language we use to rewrite it.",
    "fr": "L’esprit est le code source de l’humanité.\nL’éducation est le langage avec lequel nous le réécrivons.",
    "es": "La mente es el código fuente de la humanidad.\nLa educación es el lenguaje con el que lo reescribimos."
  },
  "translate_button_accept": {
    "it": "Consento i Termini & Cookies",
    "en": "I consent Terms & Cookies",
    "fr": "Je consens Termes & Cookies",
    "es": "Consiento Términos & Cookies"
  }
}

Sources: apps/translations.json:2-9,30-35

Page Titles (apps/pages.php)

This PHP file returns an associative array used specifically for translating the <title> tag of each page. The structure is similar to the JSON file, with a top-level key for the page identifier and a nested array of language-to-title mappings.

Structure Example:

<?php

return [
    'index' => [
        'it' => 'Benvenuto in Institute Itech',
        'en' => 'Welcome to Institute Itech',
        'fr' => 'Bienvenue chez Institute Itech',
        'es' => 'Bienvenido a Institute Itech',
    ],
    'iite_overview' => [
        'it' => 'Panoramica di Institute Itech',
        'en' => 'Overview of Institute Itech',
        'fr' => 'Vue d’ensemble de Institute Itech',
        'es' => 'Resumen de Institute Itech',
    ],
];

This array is required by the page scripts and used to set the $title variable, which is then rendered in the main layout file.
Sources: apps/pages.php:3-16, iite/overview.php:12-13

Frontend Components

A floating language switcher widget is available on the site, allowing users to change languages.

Language Switcher Widget

The widget is styled to be a circular button fixed to the bottom-right of the viewport. On hover, it reveals a menu of available languages.

CSS Class	Description	Source File
.translate	The main container for the fixed-position widget.	themes/css/iite.css:112
.container-translate > span	The circular, visible part of the button.	themes/css/iite.css:126
.lang-switcher	The pop-up menu containing the language list. It is hidden by default.	themes/css/iite.css:146
.lang-switcher.show	Class added (presumably by JavaScript) to show the language menu.	themes/css/iite.css:155
.lang-menu li	An individual language item in the menu.	themes/css/iite.css:163

The JavaScript logic for toggling the .show class on the .lang-switcher element is not present in the provided files, but its existence is implied by the CSS rules.
Sources: themes/css/iite.css:112-171

Translation Function t()

A helper function named t() is defined in each page-level PHP script to retrieve translations.

Implementation

The function takes a single argument, $key, which corresponds to a key in the translation sources. It accesses a global $translations variable (which holds the content of either pages.php or a decoded translations.json) and attempts to find a string for the current language ($lang).

It includes a fallback mechanism:

1. If a translation for the current $lang exists, it is returned.
2. In some versions of the function (e.g., index.php), it falls back to English (en) if the selected language's string is missing.
3. As a final fallback, it returns a formatted version of the key itself (e.g., ucfirst(str_replace('_', ' ', $key))).
4. Some versions also replace \n characters with <br> tags for HTML rendering.

Function Definition Example:

// From iite/overview.php
function t($key) {
    global $translations, $lang;
    return isset($translations[$key][$lang])
        ? str_replace('\n', '<br>', $translations[$key][$lang])
        : ucfirst(str_replace('_', ' ', $key));
}

Sources: iite/overview.php:16-21, index.php:15-18