ysfR3Plugin - 1.1.0

ysfR3Plugin provides R3 precompiled i18n support for symfony projects.

You are currently browsing
the website for symfony 1

Visit the Symfony2 website


« Back to the Plugins Home

Signin


Forgot your password?
Create an account

Tools

Stats

advanced search
Information Readme Releases Changelog Contribute
Show source | Show as Markdown

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 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

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:
    
    
      My Example
      Mon Exemple
    

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