r3 allows developers of web applications to customize and translate their UI for different languages, markets and uses. It allows developers to modify existing functionality and add new plug-ins via the Stickleback extension engine.
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. Through r3, you can arrange your files in small, logical units suitable for reuse. Using r3, you can save time and resources.
Copyrights for code authored by Yahoo! Inc. is licensed under the following terms:
MIT License
Copyright (c) 2006-2008 Yahoo! Inc. All Rights Reserved.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
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:
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:
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 ExampleMon 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
Dustin Whittle 
