Translation and Localization

This page documents Maho's translation and localization system, including CSV-based translation files, locale configuration, currency and timezone settings, and the infrastructure for making Maho available in multiple languages and regions.

Overview

Maho uses a CSV-based translation system where translation strings are stored in locale-specific CSV files. The platform supports multiple locales, currencies, timezones, and regional settings through configuration and can be extended with community-maintained language packs. The system is designed to handle internationalization (i18n) at the core level, ensuring that both storefront and administrative interfaces can be fully localized.

---

Translation System Architecture

Maho's translation logic is centered around the Mage_Core_Model_Translate class app/code/core/Mage/Core/Model/Translate.php13 It handles loading translation data from multiple sources, merging them based on priority, and caching the result.

Translation Loading and Merging Flow

The translation process is initialized during the application bootstrap or when switching store scopes. The init method app/code/core/Mage/Core/Model/Translate.php90-122 orchestrates the loading sequence.

Title: Translation Data Loading Sequence

Translation Merge Priority (Highest to Lowest):

1. Database Translations: Stored in the core_translate table. These are loaded via _loadDbTranslation() app/code/core/Mage/Core/Model/Translate.php115 and allow for site-specific overrides without modifying files.
2. Theme Translations: Found in the active theme's locale/{locale}/translate.csv. Loaded via _loadThemeTranslation() app/code/core/Mage/Core/Model/Translate.php114 these allow theme developers to customize strings for specific designs.
3. Module Translations: Defined in config.xml under the <translate> node for each module. Loaded via _loadModuleTranslation() app/code/core/Mage/Core/Model/Translate.php111

Sources: app/code/core/Mage/Core/Model/Translate.php13-122 app/code/core/Mage/Core/Model/Translate.php185-192

---

Locale and Regional Settings

The Mage_Core_Model_Locale class manages regional preferences, including date formats, units of measurement, and currency codes app/code/core/Mage/Core/Model/Locale.php13

Key Locale Constants

Constant	Value	File Reference
DEFAULT_LOCALE	en_US	app/code/core/Mage/Core/Model/Locale.php18
DEFAULT_TIMEZONE	UTC	app/code/core/Mage/Core/Model/Locale.php19
DEFAULT_CURRENCY	USD	app/code/core/Mage/Core/Model/Locale.php20
DATETIME_FORMAT	Y-m-d H:i:s	app/code/core/Mage/Core/Model/Locale.php25
HTML5_DATETIME_FORMAT	Y-m-d\TH:i	app/code/core/Mage/Core/Model/Locale.php27

Units of Measurement

Maho defines standard units for weight and length within the locale model to ensure consistent formatting across different regions:

• Weight: kg, lb, oz, g, t app/code/core/Mage/Core/Model/Locale.php32-36
• Length: m, cm, mm, in, ft, yd, mi, km app/code/core/Mage/Core/Model/Locale.php41-48

Locale Configuration Paths

Locale settings are retrieved from the system configuration using these XML paths:

• Locale Code: general/locale/code app/code/core/Mage/Core/Model/Locale.php53
• Timezone: general/locale/timezone app/code/core/Mage/Core/Model/Locale.php54
• Installed Currencies: system/currency/installed app/code/core/Mage/Core/Model/Locale.php57

Sources: app/code/core/Mage/Core/Model/Locale.php13-174

---

Translation in Code

The Helper Pattern

Translations are typically invoked via the __() method on a helper or block. This method acts as a proxy to the Mage_Core_Model_Translate singleton.

Title: Translation Execution Flow

Implementation Detail: The Mage_Core_Model_Translate logic handles placeholder replacement using vsprintf if arguments are provided. Developers should always use the helper's __() method to ensure the correct module scope is applied to the translation key.

CSV File Structure

Translation files use a comma-separated format where the first column is the original string (or a module-prefixed key) and the second is the translation.

• Global: Original String,Translated String app/code/core/Mage/Core/Model/Translate.php15
• Module Scoped: "Module_Name::Original String","Translated String" app/code/core/Mage/Core/Model/Translate.php16

Sources: app/code/core/Mage/Core/Model/Translate.php15-16 app/code/core/Mage/Core/Model/Translate.php202-234

---

Development Utilities

Maho provides CLI commands to maintain and debug translations:

• dev:translations:missing: Scans PHP, PHTML, and XML files for translation calls (__() or translate= attributes) and compares them against defined CSV strings to find missing translations lib/MahoCLI/Commands/TranslationsMissing.php25-27
• dev:translations:unused: Identifies strings defined in CSV files that are no longer referenced in the codebase, with an optional --remove flag to clean up the files lib/MahoCLI/Commands/TranslationsUnused.php26-35

Sources: lib/MahoCLI/Commands/TranslationsMissing.php25-27 lib/MahoCLI/Commands/TranslationsUnused.php26-35

---

Inline Translation

Inline translation allows administrators to edit translation strings directly from the storefront or admin interface using a visual overlay.

1. Detection: When enabled, the Mage_Core_Model_Translate model checks if inline translation is allowed for the current area (Frontend or Admin) via Mage_Core_Model_Translate_Inline app/code/core/Mage/Core/Model/Translate.php94-95
2. Persistence: Custom translations provided via the UI are saved to the database (table core_translate) and loaded during the initialization phase via _loadDbTranslation() app/code/core/Mage/Core/Model/Translate.php115

Sources: app/code/core/Mage/Core/Model/Translate.php94-95 app/code/core/Mage/Core/Model/Translate.php115

---

Localization of Data and Reports

Localization extends beyond text to data formatting, especially for dates and currencies.

Date and Time Handling

Maho uses native PHP DateTime and Intl extensions for regional date processing.

• Storage: Dates are stored in UTC format 'Y-m-d H:i:s' in the database app/code/core/Mage/Core/Model/Locale.php25
• Formatting: Mage_Core_Model_Locale provides constants for different format types: full, long, medium, and short app/code/core/Mage/Core/Model/Locale.php62-65
• Utility Methods: Mage_Core_Helper_Data::formatDate() app/code/core/Mage/Core/Helper/Data.php152-155 and formatTimezoneDate() app/code/core/Mage/Core/Helper/Data.php158-175 provide locale-aware output based on store settings.
• Report Localization: Report resources use Mage_Core_Model_Locale::formatDateForDb() to ensure dates are correctly normalized for database storage app/code/core/Mage/Reports/Model/Resource/Report/Abstract.php55

Currency and Numeric Optimization

• Caching: Mage_Core_Model_Locale maintains a static cache for currency objects ($_currencyCache) and NumberFormatter instances ($_numberFormatterCache) to improve performance app/code/core/Mage/Core/Model/Locale.php88-90
• Currency Formatting: Mage_Core_Helper_Data::currency() handles price conversion and formatting for the current or specified store view app/code/core/Mage/Core/Helper/Data.php88-115
• Currency Configuration: Allowed currencies and installed currencies are managed via XML paths global/locale/allow/currencies and system/currency/installed app/code/core/Mage/Core/Model/Locale.php56-57

Sources: app/code/core/Mage/Core/Model/Locale.php25-90 app/code/core/Mage/Core/Model/Locale.php56-57 app/code/core/Mage/Core/Helper_Data.php88-175 app/code/core/Mage/Reports/Model/Resource/Report/Abstract.php55