# ysfR3Plugin - A precompiled translation system for the symfony framework

ysfR3Plugin allows you to integrate the symfony project with the Yahoo R3 project. Yahoo! r3 is an extensible open-source tool for building and maintaining variant web sites by creating, managing and localizing templates and translations. It can be controlled using both web and command line interfaces which generate text based files for use in internationalized applications. These outputs may take the form of templates, configuration files or even source code. r3 can save and load translation data in XLIFF format. It can be extended using Stickleback, a unique and powerful plugin engine. It can also be embedded into third party applications. If you are managing a website across multiple locations (e.g. the US, the UK and Japan), then you face the challenge of accommodating each location's language and possible page layout requirements. The ideal is to reuse common components as much as possible, and still allow room for differentiation.

R3 integration works by adding a precompile stage to templates/configurations where you can use special r3 markup tags, as well as use the r3 translation store to power symfony's built in i18n system (__()).

  **For more information about r3, please see http://developer.yahoo.com/r3/ and http://www.openr3.com/.**


## Getting Started

### Requirements

  **ysfR3Plugin uses APC by default and it should be enabled in the command line. In addition, ysfR3Plugin is designed to be used in conjunction with the ysfDimensionsPlugin to provide complete i18n capabilities to symfony.**


### Installation

  **1. Install r3 (and dependencies) via pear**

    
    pear install --alldeps r3 stickleback
    

  **2. Install and configure ysfDimensionsPlugin**

    
    symfony plugin:install ysfDimensionsPlugin
    


  **3. Install the plugin via the symfony cli**

    
    symfony plugin:install ysfR3Plugin
    

  **4. Clear symfony cache**

    
    symfony cache:clear
    


### Configuration

  **1. Configure your application configuration to use this plugin**

    
    // manually require class since not part of symfony core
    require_once(dirname(__FILE__).'/../../../plugins/ysfR3Plugin/lib/config/ysfR3ApplicationConfiguration.class.php');
    

Edit apps/example/config/exampleConfiguration.class.php changing the parent class from sfApplicationConfiguration to **ysfR3ApplicationConfiguration**.

Now that the i18n hooks are in place, you need to configure your application, by following the steps below:

  **2. Update i18n factory**

First we need to define the i18n factory in factories.yml:
    
    all:
      i18n:
        class: ysfR3I18N
        param:
          source:               R3      # i18n source
          database:             %SF_DATA_DIR%/i18n/r3
          debug:                off     # debug mode enabled?
          untranslated_prefix:  "[t]"   # prefix for untranslated strings
          untranslated_suffix:  "[/t]"  # suffix for untranslated strings
          default_culture:      en_US
          allowed_cultures:     [en_GB, es_ES, de_DE, fr_FR, it_IT ]( en_US,)  # allowed cultures
          translate_markup:     r3:trans
          cache:
            class: sfAPCCache
            param:
              automatic_cleaning_factor: 0
              lifetime:                  31556926
              prefix:                    %SF_APP_DIR%/i18n
    


  **3. Clear symfony cache**

    
    symfony cache:clear
    

There are some required parameters for the ysfR3I18n factory, primarily: source, database, and allowed_cultures.

## Examples

So what's really going on here? Let's talk a little about each of these.

### Using r3 in templates

The r3 integration works like the native __() method. Unlike the __() method,
r3 translations do not occur each request. Instead of using __(), there are <r3:trans></r3:trans> tags
that can be used in any configuration or template file.

If we want to localize a string in a template:

Let's try internationalizing the apps/frontend/modules/demo/templates/testSuccess.php template:

    
    <h1><r3:trans>Hello World!</r3:trans></h1>
    <p><r3:trans>We are in the test template now.</r3:trans></p>
    


  **When symfony looks for the template, r3 will translate the text in the r3:trans tags and create a
localized cache template in project/cache/i18n/$culture/apps/frontend/modules/demo/templates/testSuccess.php.
On every subsequent request the translation will not occur and symfony will use the localized file.**


### Using r3 in configuration files

Now we just need to establish the setting itself.  This is an app-level setting
(app_) so it belongs in the app.yml file.  Let's create a base value.  Create
apps/frontend/config/view.yml:

    
    default:
      metas:
        title:    <r3:trans>My Example</r3:trans>
        keywords: <r3:trans>symfony</r3:trans>, <r3:trans>project</r3:trans>, <r3:trans>framework</r3:trans>
    


### Updating translations via r3 message source

apps/frontend/modules/demo/actions/actions.class.php
    
    <?php
    
    public function executeTest()
    {
      $this->getI18n()->getMessageSource()->setCulture('fr');
      $this->getI18n()->getMessageSource()->update('My Example', 'Mon Exemple', '');
    
      return $this->renderText($this->getI18n()->__('My Example'));
    }
    

Now try changing the culture to fr and see the results.


### Updating translations via xliff dictionaries

Export xliff with symfony cli:
    
    symfony i18n:export-xliff
    

Update xliff in data/i18n/messages.xml:
    
    <trans-unit id='123' approved='yes'>
      <source>My Example</source>
      <target>Mon Exemple</target>
    </trans-unit>
    

Import xliff with symfony cli:
    
    symfony i18n:import-xliff
    

Now try changing the culture to fr and see the results.


### Generating cache for all translations

Use symfony cli to translate entire project:
    
    symfony i18n:translate
    

You'll need to clear the cache.


## Performance

Installing the ysfR3Plugin adds overhead to your project in development. This is the cost
of translating all the templates and configurations at run time (and monitoring if they have changed since last request).
In production all translations are cached and so are the paths to the localized paths, so the i18n
is much faster as it does not happen every request.


## Tests

For a complete example of how to use and test applications with r3,
please see the functional test project in plugins/ysfR3Plugin/test/fixtures/project.


## License

Please see the packaged LICENSE file for the details of the MIT license.


## Todo

  * Ajax inline edit (in-context) for translation updates