Development

Changeset 10941

You must first sign up to be able to contribute.

Changeset 10941

Show
Ignore:
Timestamp:
08/19/08 00:23:09 (5 years ago)
Author:
dwhittle
Message:

ysfR3Plugin: converted README to markdown format

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • plugins/ysfR3Plugin/branches/1.1/README

    r9332 r10941  
    1 = ysfR3Plugin - A precompiled translation system for the symfony framework = 
     1ysfR3Plugin 
     2=========== 
    23 
    34ysfR3Plugin 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. 
    …… 
    56R3 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 (__()). 
    67 
    7 '''For more information about r3, please see http://developer.yahoo.com/r3/ and http://www.openr3.com/.''' 
    8  
    9  
    10 == Getting Started == 
    11  
    12 === Requirements === 
    13  
    14 '''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.''' 
    15  
    16  
    17 === Installation === 
    18  
    19 '''1. Install r3 (and dependencies) via pear''' 
    20  
    21 {{{ 
    22 pear install --alldeps r3 stickleback 
    23 }}} 
    24  
    25 '''2. Install and configure ysfDimensionsPlugin''' 
    26  
    27 {{{ 
    28 symfony plugin:install ysfDimensionsPlugin 
    29 }}} 
    30  
    31  
    32 '''3. Install the plugin via the symfony cli''' 
    33  
    34 {{{ 
    35 symfony plugin:install ysfR3Plugin 
    36 }}} 
    37  
    38 '''4. Clear symfony cache''' 
    39  
    40 {{{ 
    41 symfony cache:clear 
    42 }}} 
    43  
    44  
    45 === Configuration === 
    46  
    47 '''1. Configure your application configuration to use this plugin''' 
    48  
    49 {{{ 
    50 // manually require class since not part of symfony core 
    51 require_once(dirname(__FILE__).'/../../../plugins/ysfR3Plugin/lib/config/ysfR3ApplicationConfiguration.class.php'); 
    52 }}} 
    53  
    54 Edit apps/example/config/exampleConfiguration.class.php changing the parent class from sfApplicationConfiguration to '''ysfR3ApplicationConfiguration'''. 
     8*For more information about r3, please see (http://developer.yahoo.com/r3/) and (http://www.openr3.com/).* 
     9 
     10 
     11Requirements 
     12------------ 
     13 
     14*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.* 
     15 
     16 
     17Installation 
     18------------ 
     19 
     20*1. Install r3 (and dependencies) via pear* 
     21   
     22    pear install --alldeps r3 stickleback 
     23 
     24 
     25*2. Install and configure ysfDimensionsPlugin* 
     26 
     27    symfony plugin:install ysfDimensionsPlugin 
     28 
     29 
     30*3. Install the plugin via the symfony cli* 
     31 
     32    symfony plugin:install ysfR3Plugin 
     33 
     34 
     35*4. Clear symfony cache* 
     36 
     37    symfony cache:clear 
     38 
     39 
     40 
     41Configuration 
     42------------- 
     43 
     44*1. Configure your application configuration to use this plugin* 
     45 
     46 
     47    // manually require class since not part of symfony core 
     48    require_once(dirname(__FILE__).'/../../../plugins/ysfR3Plugin/lib/config/ysfR3ApplicationConfiguration.class.php'); 
     49 
     50Edit apps/example/config/exampleConfiguration.class.php changing the parent class from sfApplicationConfiguration to *ysfR3ApplicationConfiguration*. 
    5551 
    5652Now that the i18n hooks are in place, you need to configure your application, by following the steps below: 
    5753 
    58 '''2. Update i18n factory''' 
     54*2. Update i18n factory* 
    5955 
    6056First we need to define the i18n factory in factories.yml: 
    61 {{{ 
    62 all: 
    63   i18n: 
    64     class: ysfR3I18N 
    65     param: 
    66       source:               R3      # i18n source 
    67       database:             %SF_DATA_DIR%/i18n/r3 
    68       debug:                off     # debug mode enabled? 
    69       untranslated_prefix:  "[t]"   # prefix for untranslated strings 
    70       untranslated_suffix:  "[/t]"  # suffix for untranslated strings 
    71       default_culture:      en_US 
    72       allowed_cultures:     [ en_US, en_GB, es_ES, de_DE, fr_FR, it_IT ]  # allowed cultures 
    73       translate_markup:     r3:trans 
    74       cache: 
    75         class: sfAPCCache 
     57 
     58 
     59    all: 
     60      i18n: 
     61        class: ysfR3I18N 
    7662        param: 
    77           automatic_cleaning_factor: 0 
    78           lifetime:                  31556926 
    79           prefix:                    %SF_APP_DIR%/i18n 
    80 }}} 
    81  
    82  
    83 '''3. Clear symfony cache''' 
    84  
    85 {{{ 
    86 symfony cache:clear 
    87 }}} 
     63          source:               R3      # i18n source 
     64          database:             %SF_DATA_DIR%/i18n/r3 
     65          debug:                off     # debug mode enabled? 
     66          untranslated_prefix:  "[t]"   # prefix for untranslated strings 
     67          untranslated_suffix:  "[/t]"  # suffix for untranslated strings 
     68          default_culture:      en_US 
     69          allowed_cultures:     [ en_US, en_GB, es_ES, de_DE, fr_FR, it_IT ]  # allowed cultures 
     70          translate_markup:     r3:trans 
     71          cache: 
     72            class: sfAPCCache 
     73            param: 
     74              automatic_cleaning_factor: 0 
     75              lifetime:                  31556926 
     76              prefix:                    %SF_APP_DIR%/i18n 
     77 
     78 
     79*3. Clear symfony cache* 
     80 
     81 
     82    symfony cache:clear 
     83 
    8884 
    8985There are some required parameters for the ysfR3I18n factory, primarily: source, database, and allowed_cultures. 
    9086 
    91 == Examples == 
     87Examples 
     88-------- 
    9289 
    9390So what's really going on here? Let's talk a little about each of these. 
    9491 
    95 === Using r3 in templates === 
     92Using r3 in templates 
     93--------------------- 
    9694 
    9795The r3 integration works like the native __() method. Unlike the __() method, 
    …… 
    10199If we want to localize a string in a template: 
    102100 
    103 Let's try internationalizing the apps/frontend/modules/demo/templates/testSuccess.php template: 
    104  
    105 {{{ 
    106 <h1><r3:trans>Hello World!</r3:trans></h1> 
    107 <p><r3:trans>We are in the test template now.</r3:trans></p> 
    108 }}} 
    109  
    110  
    111 '''When symfony looks for the template, r3 will translate the text in the r3:trans tags and create a 
     101Let's try localizing the apps/frontend/modules/demo/templates/testSuccess.php template: 
     102   
     103  <h1><r3:trans>Hello World!</r3:trans></h1> 
     104  <p><r3:trans>We are in the test template now.</r3:trans></p> 
     105 
     106 
     107*When symfony looks for the template, r3 will translate the text in the r3:trans tags and create a 
    112108localized cache template in project/cache/i18n/$culture/apps/frontend/modules/demo/templates/testSuccess.php. 
    113 On every subsequent request the translation will not occur and symfony will use the localized file.''' 
    114  
    115  
    116 === Using r3 in configuration files === 
     109On every subsequent request the translation will not occur and symfony will use the localized file.* 
     110 
     111 
     112Using r3 in configuration files 
     113------------------------------- 
    117114 
    118115Now we just need to establish the setting itself.  This is an app-level setting 
    …… 
    120117apps/frontend/config/view.yml: 
    121118 
    122 {{{ 
    123 default: 
    124   metas: 
    125     title:    <r3:trans>My Example</r3:trans> 
    126     keywords: <r3:trans>symfony</r3:trans>, <r3:trans>project</r3:trans>, <r3:trans>framework</r3:trans> 
    127 }}} 
    128  
    129  
    130 === Updating translations via r3 message source === 
     119     
     120    default: 
     121      metas: 
     122        title:    <r3:trans>My Example</r3:trans> 
     123        keywords: <r3:trans>symfony</r3:trans>, <r3:trans>project</r3:trans>, <r3:trans>framework</r3:trans> 
     124 
     125 
     126Updating translations via r3 message source 
     127------------------------------------------- 
    131128 
    132129apps/frontend/modules/demo/actions/actions.class.php 
    133 {{{ 
    134 <?php 
    135  
    136 public function executeTest() 
    137 { 
    138   $this->getI18n()->getMessageSource()->setCulture('fr'); 
    139   $this->getI18n()->getMessageSource()->update('My Example', 'Mon Exemple', ''); 
    140  
    141   return $this->renderText($this->getI18n()->__('My Example')); 
    142 } 
    143 }}} 
     130 
     131 
     132    <?php 
     133     
     134    public function executeTest() 
     135    { 
     136      $this->getI18n()->getMessageSource()->setCulture('fr'); 
     137      $this->getI18n()->getMessageSource()->update('My Example', 'Mon Exemple', ''); 
     138     
     139      return $this->renderText($this->getI18n()->__('My Example')); 
     140    } 
     141 
    144142 
    145143Now try changing the culture to fr and see the results. 
    146144 
    147145 
    148 === Updating translations via xliff dictionaries === 
     146Updating translations via xliff dictionaries 
     147-------------------------------------------- 
    149148 
    150149Export xliff with symfony cli: 
    151 {{{ 
    152 symfony i18n:export-xliff 
    153 }}} 
     150 
     151    symfony i18n:export-xliff 
     152 
    154153 
    155154Update xliff in data/i18n/messages.xml: 
    156 {{{ 
    157 <trans-unit id='123' approved='yes'> 
    158   <source>My Example</source> 
    159   <target>Mon Exemple</target> 
    160 </trans-unit> 
    161 }}} 
     155 
     156 
     157    <trans-unit id='123' approved='yes'> 
     158      <source>My Example</source> 
     159      <target>Mon Exemple</target> 
     160    </trans-unit> 
     161 
    162162 
    163163Import xliff with symfony cli: 
    164 {{{ 
    165 symfony i18n:import-xliff 
    166 }}} 
     164 
     165    symfony i18n:import-xliff 
    167166 
    168167Now try changing the culture to fr and see the results. 
    169168 
    170169 
    171 === Generating cache for all translations === 
     170Generating cache for all translations 
     171------------------------------------- 
    172172 
    173173Use symfony cli to translate entire project: 
    174 {{{ 
    175 symfony i18n:translate 
    176 }}} 
     174 
     175 
     176    symfony i18n:translate 
     177 
    177178 
    178179You'll need to clear the cache. 
    179180 
    180181 
    181 == Performance == 
     182Performance 
     183----------- 
    182184 
    183185Installing the ysfR3Plugin adds overhead to your project in development. This is the cost 
    …… 
    187189 
    188190 
    189 == Tests == 
     191Tests 
     192----- 
    190193 
    191194For a complete example of how to use and test applications with r3, 
    …… 
    193196 
    194197 
    195 == License == 
     198License 
     199------- 
    196200 
    197201Please see the packaged LICENSE file for the details of the MIT license. 
    198202 
    199203 
    200 == Todo == 
     204Todo 
     205---- 
    201206 
    202207  * Ajax inline edit (in-context) for translation updates