Skip to content

Internationalisation

Jump to bottom
Ed Mozley edited this page Jun 1, 2026 · 7 revisions

Internationalisation (i18n)

FreeITSM has native multi-language support built in — no framework, no build step, no external translation service. UI strings are looked up at render time through a tiny t('namespace.key') helper that works identically in PHP and JavaScript, with automatic per-key fallback to English.

The active language follows the logged-in analyst's preference (set in System → Preferences), so two analysts on the same install can use the product in different languages.

Supported locales (20)
en English af Afrikaans fr Français de Deutsch
es Español pt-BR Português (BR) nl Nederlands it Italiano
pl Polski ru Русский id Bahasa Indonesia hi हिन्दी
bn বাংলা ta தமிழ் te తెలుగు mr मराठी
kn ಕನ್ನಡ ml മലയാളം gu ગુજરાતી pa ਪੰਜਾਬੀ

Adding a language is a code change (add it to I18n::SUPPORTED_LOCALES and create the lang/<code>/ folder) — deliberate, so the locale parameter can never be used for path traversal. Locale codes follow BCP 47 (the same form used in the HTML lang attribute).

How it works

  • Lang files live at lang/<locale>/<module>.php and return a nested PHP array. The first dot-segment of a t() key is the filename; the rest walks the array. t('cmdb.nav.browse') → lang/<locale>/cmdb.php → ['nav']['browse'].
  • PHP calls t('cmdb.nav.browse') (or htmlspecialchars(t(...)) for HTML output). Defined in includes/i18n.php.
  • JavaScript calls window.t('cmdb.nav.browse'). The host page injects window.translations from I18n::exportForJs([...]) with the English fallback already merged in per key; the JS bridge (assets/js/i18n.js) just walks the dotted path.
  • Per-key fallback. If a locale file is missing a key (or doesn't exist at all), that single string falls back to English — everything else in the locale still applies. A completely unfilled key surfaces as the literal key, so gaps are visible during development rather than rendering blank.
  • Interpolation. t('common.welcome', ['name' => 'Ed']) substitutes {name}. Unknown placeholders are left intact.
  • Locale resolution (priority order): analyst's interface_language preference → browser Accept-Language (best supported match, primary-subtag fallback) → en. Changing it in Preferences persists to user_preferences and reloads the page.
  • Security. Namespace identifiers are regex-validated; locale codes are checked against the supported list before being used as a path; the JS bridge JSON is emitted with JSON_HEX_* flags to prevent script-tag injection from a translation value.

Module coverage

Fully translated across all 20 locales (every user-facing string in PHP and JavaScript):

Tickets · Tasks · Process Mapper · Workflows · Knowledge · Change Management · Asset Management · Calendar · Service Status · CMDB

The remaining modules (Contracts, Morning Checks, Watchtower, Reporting, Software, Forms, LMS, Network Mapper, Self-Service, System) render in English today and are converted module-by-module. Last updated: 2026-06-02.

What is not translated, by design: user-authored and configurable data — CMDB CI values and user-defined class/property names, knowledge-article content, supplier/contract records, incident update text, etc. These are data, not UI chrome, so they always display as entered.

Converting a module

The pattern is mechanical and mirrors any already-converted module (Tasks is the canonical reference):

  1. Extract every user-facing string into lang/en/<module>.php as a grouped nested array (nav, list, settings, toast, help, …).
  2. Wire each full-HTML page: require_once 'includes/i18n.php'; I18n::initFromSession();, set $translationNamespaces = ['common', '<module>'], set <html lang="<?php echo htmlspecialchars(I18n::getLocale()); ?>">, and emit the window.translations + i18n.js block in <head>.
  3. Replace literals — PHP <?php echo htmlspecialchars(t('<module>.key')); ?>, JS window.t('<module>.key', {param}).
  4. Add the locale files lang/<locale>/<module>.php for the other 19 languages. Missing keys fall back to English, so a partial file is always valid — you can ship incrementally.

Reuse the shared common.* namespace for cross-cutting strings (buttons, calendar month/weekday names) rather than duplicating them per module.

Files

Path Purpose
includes/i18n.php I18n class + global t(); locale resolution, fallback, interpolation, exportForJs()
assets/js/i18n.js Client-side window.t() mirroring the PHP contract
lang/<locale>/<module>.php Per-locale, per-module translation arrays
lang/<locale>/common.php Shared strings (buttons, calendar primitives, module names, account menu)

FreeITSM — an open-source IT Service Management platform · github.com/edmozley/freeitsm · MIT licence

FreeITSM

Getting Started

Modules

Multi-tenancy (planned)

Blue sky thinking

Bugs resolved

Links

Clone this wiki locally