ullright Internationalisation / Multilanguage / i18n

Introduction

ullright provides powerful multilanguage support. Out of the box we currently support english and german, but any other language can be added.

If multilanguage support is enabled, you can change the interface language anytime.

Note: Example filenames are for german translations (de)

Setup

There are two settings for multilanguage support:

  1. In apps/frontend/config/settings.yml enable i18n and set the default language.
    (It is called "culture" in the symfony context)

    all:
      .settings:
        i18n:                   true
        default_culture:        en
  2.  In apps/frontend/config/apps.yml there is a list of supported languages "supported_languages":

    all: 
      i18n:  
        supported_languages: [ 'de', 'en' ]
    
    

The example above enables multilange support providing english and german.

Another example for german only site:

  1. apps/frontend/config/settings.yml
     

    Note: i18n is left enabled, to be able to easily add multilanguage support later on

    all:
      .settings:
        i18n:                   true
        default_culture:        de
  2.  apps/frontend/config/apps.yml

    all: 
      i18n:  
        supported_languages: [ 'de']
    
    

Types of Translation

There are two different translation mechanisms at work:

  1. Interface translations in templates
  2. Database translations for columns in database tables

This article will explain the interface translation part for now.

Interface Translation

Interface translation in ullright are very simple. There are dictionary files (XML) foreach language. Then in the templates the __() helper is used for multilanguage output which uses a dictionary to translate a string.

Dictionaries

Your custom translations go into apps/frontend/i18n/custom.de.xml

Here is an example:
 

<?xml version="1.0"?>
<xliff version="1.0">
  <file orginal="global" source-language="en_US" datatype="plaintext" date="2007-12-13T14:54:05Z">
    <body>


<trans-unit id="1">
  <source>Apple</source>
  <target>Apfel</target>
</trans-unit>

    </body>
  </file>
</xliff>

For each further translation add a similar "trans-unit" block and increment the id.

Translation Helper for the Templates

The counterpart for the dictionary is the helper for the templates.

Let's use a translation in layout.php for example:

<div id="header">
  <?php echo __('Apple', null, 'custom') ?>
</div>

 The "__()" function takes three arguments:

  1. The string to translate - If no translation is found the actual string is used
  2. An array of translation options (Advanced usage)
  3. The name of the dictionary

To use html tags in translations use open and closing tag replacement as tags are not supported!!!

  • __('Invalid code. Please try again or %otag%request a new code%ctag%.', [
                    '%otag%' => '<a href="' . url_for('my/url') . '">',
                    '%ctag%' => '</a>',
                  ], 'ullCoreMessages'
              )
  •       <trans-unit id="6009">
            <source>Invalid code. Please try again or %otag%request a new code%ctag%.</source>
            <target>Ungültiger code. Bitte versuchen Sie es erneut oder %otag%fordern Sie einen neuen Code an%ctag%.</target>
          </trans-unit> 

 

For advanced usage please read the capter in the symfony book:

http://symfony.com/legacy/doc/gentle-introduction/1_4/en/13-I18n-and-L10n

Information for ullright core developers 

Common phrases which are used throughout all ullright plugins are added to plugins/ullCorePlugin/i18n/common.de.xml.

Unfortunatly some symfony-built-in translations e.g. for form error messages are hardcoded to use apps/frontend/i18n/messages.de.xml.

Therefore we moved apps/frontend/i18n/messages.de.xml to plugins/ullCorePlugin/i18n/common.de.xml and created a symlink for it in apps/frontend/i18n/. Do not edit this file for custom Translations!

Use the "custom" dictionary file instead (see above)

Plugin specific translations go into plugins/ullPlugin/i18n/ullPluginMessages.de.xml

 

i18n Database Queries

Doctrine, join Translations, but queries all languages:

  •       $q = new Doctrine_Query;
          $q
            ->from('UllCmsContentBlock cb, cb.Translation t')
            ->where('slug = ?', $slug)
          ;
          
          return $q->fetchOne();

ullQuery, selects only the current language automatically:

  •       $q = new ullQuery('UllCmsContentBlock');
          $q
            ->select(['*', 'Translation->*'])
            ->where('slug = ?', $slug)
          ;
          
          return $q->fetchOne();