Polyglot

Polyglot is a core application within UNA Studio designed to manage all aspects of internationalization (i18n) and localization (l10n) for your UNA site. It allows administrators to control language settings, manage translations for all text displayed on the site, customize system emails, and set regional formatting preferences.

For developers, Polyglot provides the framework for creating multilingual modules and ensuring that all user-facing text and communications can be easily translated and adapted to different locales. Properly utilizing Polyglot is essential for creating a globally accessible and user-friendly UNA site.

Core Concepts

  • Language Pack: A collection of translations for a specific language (e.g., French, German, Spanish). Language packs are installed like other UNA apps via the App Store and contain translated strings for the core system and installed modules.
  • Language Key (String Key): A unique identifier (e.g., _bx_posts_form_caption_title) used in the code and templates to represent a piece of text. Polyglot maps this key to the actual translated text for the currently active language.
  • Translation: The actual text string in a specific language corresponding to a language key.
  • Default Language: The language displayed to visitors by default if no other language preference is detected or selected.
  • Macros: Placeholders used within email templates (e.g., {site_name}, {recipient_name}) that are dynamically replaced with actual values when the email is sent.
  • Date/Time Formatting: Standardized codes (based on PHP's date() function) used to define how dates and times are displayed across the site.

Accessing Polyglot

Polyglot is accessed from the main navigation within the UNA administration backend:

  1. Log in to your UNA site's Studio.
  2. Navigate to the Polyglot menu item (often represented by a globe or translation icon).

Managing Language Settings (Settings Tab)

This section allows administrators to configure site-wide language and regional preferences.

  • Default Language: Select the primary language for your site from the dropdown list of installed language packs. Users may still be able to switch languages if enabled elsewhere, but this sets the fallback language.
  • Date Format: Define the format for displaying dates (e.g., day, month, year). Uses standard PHP date() format codes. Example: d M Y (01 Jan 2023), m/d/Y (01/01/2023).
  • Time Format: Define the format for displaying times (e.g., hours, minutes, AM/PM). Uses standard PHP date() format codes. Example: H:i (14:30), g:i A (2:30 PM).
  • Datetime Format: Define the combined format for displaying both date and time. Example: d M Y H:i (01 Jan 2023 14:30).
  • Use 'time ago' format for dates less than this number of seconds: Set a threshold (in seconds) below which dates/times will be displayed relatively (e.g., "2 hours ago", "5 minutes ago"). If the time difference exceeds this value, the standard Datetime Format will be used. A common value might be 86400 (one day).

Managing Language Keys (Keys Tab)

This is the core translation management interface where administrators can view, search, add, edit, and delete language keys and their translations for all installed modules.

  • Interface:
    • Module Filter: Select a specific module from the dropdown to view only its language keys. Choose "All" to view keys from all modules.
    • Search: Find specific keys or translations by entering text into the search bar.
  • Managing Keys:
    • View: Lists all keys for the selected module/search criteria, showing the key name and its translation in the currently selected language for editing.
    • Add Key: Allows adding a new language key. You must provide a unique key name and its translation in the default language. Note: Adding keys here is generally less common than developers defining them within their modules.
    • Edit Key: Click on a key's translation text to modify it for the currently selected editing language. This is the primary way administrators provide or correct translations.
    • Delete Key: Removes a language key and all its translations. Use with extreme caution! Deleting a key used by the system or a module will result in the key name being displayed instead of text (e.g., _bx_posts_form_caption_title shown directly to the user). Deletion should generally only be considered for keys added by mistake or keys belonging to uninstalled custom modules.

Developer Perspective: Working with Language Keys

Developers are responsible for defining and using language keys within their modules.

  1. Defining Keys: Language keys for a module are defined in language files, typically starting with en.xml, located in the module's /data/langs/system/ directory (e.g., /modules/vendor/mymodule/data/langs/system/en.xml). The structure is simple XML:

    <?xml version="1.0" encoding="utf-8"?>
<resources name="en" flag="gb" title="English">
    <string name="_vendor_mymodule_key_name"><![CDATA[This is the English text.]]></string>
    <string name="_vendor_mymodule_another_key"><![CDATA[Another piece of text.]]></string>
    <!-- Add all module strings here -->
</resources>
    • Naming Convention: Keys should follow the format _[vendor]_[module_name]_[description] (e.g., _bx_posts_form_caption_title, _my_company_polls_results_link). This ensures uniqueness across modules.
    • The module's installer should register these language files.

  2. Using Keys in PHP: Use the _t() function to retrieve the translation for the current language.

    // Get translated string
$sTitle = _t('_vendor_mymodule_page_title');
echo MsgBox(_t('_vendor_mymodule_msg_success'));

// Using sprintf with translations
$sMessage = _t('_vendor_mymodule_welcome_user', $sUserName); // Assumes key value is "Welcome, %s!"

  3. Using Keys in Templates (.html): Use the double underscore syntax or the bx_text function.

    <!-- Option 1: Double Underscore -->
<h2>__vendor_mymodule_page_title__</h2>
<bx_button caption="__vendor_mymodule_button_submit__" />

<!-- Option 2: bx_text function -->
<h2>{{ bx_text:_vendor_mymodule_page_title }}</h2>

Managing System Emails (Emails Tab)

This section allows administrators to customize the content of automated emails sent by UNA and its modules (e.g., registration confirmation, notifications, password reset).

  • Interface: Lists all registered email templates, grouped by module. You can search for specific templates.
  • Editing Templates: Click on an email template to edit its properties:
    • System Name: An internal identifier for the template (not usually edited).
    • Subject: The subject line of the email. Can contain macros.
    • Body: The HTML content of the email. Can contain macros. Use the rich text editor for formatting.
  • Macros: Placeholders like {site_name}, {recipient_name}, {recipient_email}, {confirm_url} are replaced with dynamic data when the email is generated. The available macros depend on the specific email template and the module that sends it. Hovering over macros in the editor often shows their description.

Developer Perspective: Defining Email Templates

Modules that send emails should define their email templates using the BxDolEmailTemplates system.

  1. Define Template in Code/DB: Email templates (key name, default subject, default body) are typically added to the sys_email_templates database table during module installation via the Installer class.
  2. Triggering Emails: Use sendMail() method of BxDolEmailTemplates class to send emails using a registered template key. Pass dynamic data for macros as an array.
    // Example sending an email
bx_import('BxDolEmailTemplates');
$aReplacements = [
    'recipient_name' => $sUserName,
    'activation_link' => $sActivationUrl,
    'site_name' => getParam('site_title'), // Example macro value
];
sendMail('my_template_key', 0, $iRecipientProfileId, $aReplacements);

Managing Global Email Template (Email Template Tab)

This section allows administrators to define a consistent header and footer that wraps all emails sent through the BxDolEmailTemplates system.

  • Purpose: Apply branding (logos, colors), add standard links (privacy policy, contact), or include legal disclaimers consistently across all system emails.
  • Editing: Provides editors for the Header and Footer HTML content.
  • Macros: Common macros available here include {site_name}, {site_url}, {header_text}, {footer_text}, {about_us}, {unsubscribe} (though unsubscribe functionality might depend on context).

Best Practices

  • For Administrators:
    • Regularly review translations, especially after installing new apps or language packs.
    • Keep date/time formats consistent with your target audience's expectations.
    • Customize system emails to match your site's branding and tone.
    • Use the global email template for consistent branding.
  • For Developers:
    • Never hardcode user-facing text. Always use language keys.
    • Follow the standard naming convention for language keys (_vendor_module_description).
    • Define all default English strings in your module's en.xml file.
    • Define email templates for all emails sent by your module.
    • Provide clear descriptions for any custom macros used in your email templates.

Troubleshooting

  • Keys Showing Instead of Text: The language key is missing a translation for the current language, or the key itself was deleted or never defined. Check the Keys tab in Polyglot for the specific key and language. Ensure the module defining the key is installed and enabled. Clear DB Cache.
  • Emails Not Sending: This is typically unrelated to Polyglot content editing but rather the site's main mailer settings (Studio > Settings > Site Settings > Mailer). Ensure the mailer is configured correctly.
  • Macros Not Working: Ensure the macro name is spelled correctly (case-sensitive) within curly braces {}. Verify that the module sending the email is actually providing a value for that specific macro.
On This Page