enhancement(i18n): evaluate replacing custom translation system with a third-party library

[JohnVillalovos]

Summary

Analysis for this issue proposal was performed by Claude.

LibreBooking currently uses a custom translation system built around locale-specific PHP classes in lang/, Resources::GetInstance()->GetString(...) in PHP, and a Smarty {translate} helper in templates.

This works, but it increases maintenance cost and limits some modern i18n capabilities. We should evaluate whether LibreBooking would benefit from migrating to a well-supported third-party translation library instead of continuing to extend the current in-house approach.

Current State

Today the application uses:

• Locale-specific PHP language definitions under lang/
• Resources::GetInstance()->GetString(...) for translated strings in PHP
• Smarty {translate ...} plugin usage in templates
• Localized template fallback to en_us
• Config-based string overrides via config/lang-overrides.php

Notable limitations of the current approach:

• Custom implementation to maintain long-term
• No built-in ICU message formatting
• Limited pluralization/select support
• Harder integration with standard translation tooling
• Some string formatting is implemented with sprintf-style substitution in custom code

Proposal

Investigate migrating LibreBooking’s translation layer to a third-party PHP i18n library.

Initial candidates to evaluate:

• symfony/translation
• gettext/gettext

symfony/translation appears like the strongest initial candidate because it can be used as a standalone component and would likely support an incremental migration path while preserving the existing Smarty and PHP translation call sites behind an adapter.

Goals

• Reduce maintenance burden of the custom translation framework
• Improve pluralization and message-formatting support
• Support more standard translation file formats and tooling
• Make translation behavior more predictable and testable
• Preserve existing LibreBooking language coverage during migration

Non-Goals

• Rewriting all translations immediately
• Removing all existing language files in a single change
• Changing user-visible wording as part of the initial exploration

Evaluation Criteria

• Compatibility with PHP 8.2+
• Ease of integrating with Smarty templates
• Incremental migration feasibility
• Support for fallback locales
• Support for pluralization and ICU-style messages
• Ability to preserve or replace current language override behavior
• Impact on translator workflow
• Long-term maintenance and ecosystem health

Suggested Approach

1. Prototype one candidate library behind the existing translation interface.
2. Keep current call sites stable where possible:
   • PHP: Resources::GetInstance()->GetString(...)
   • Smarty: {translate ...}
3. Migrate one small slice first to validate ergonomics and compatibility.
4. Compare complexity, performance, and developer/translator workflow before deciding.

Open Questions

• Should LibreBooking standardize on ICU messages during migration, or preserve existing key/value semantics first?
• Should email/template localization stay file-based or be folded into the same translation backend?
• How should config/lang-overrides.php be represented in the new model?
• Is gettext-style translator workflow preferable to app-native PHP/YAML/XLIFF catalogs?

Acceptance Criteria

• A recommended library is selected, or the team decides to keep the custom system with documented reasons
• Risks, migration strategy, and compatibility implications are documented
• A follow-up implementation issue can be created with clear scope