Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Started writing the translations stuff doc

  • Loading branch information...
commit 7998ed3aba80f4861f4a59530fa6a964022858e2 1 parent d0e9702
authored December 09, 2011

Showing 1 changed file with 159 additions and 0 deletions. Show diff stats Hide diff stats

  1. 159  README.markdown
159  README.markdown
Source Rendered
@@ -265,6 +265,7 @@ class DocumentRepository extends BaseDocumentRepository implements RepositoryIdI
265 265
 <tr><td> ReferenceOne(targetDocument="myDocument", weak=false):  </td><td>Refers a document of the type myDocument. The default is a weak reference. By optionaly specifying weak=false you get a hard reference. It is optional to specify the targetDocument, you can reference any document.</td></tr>
266 266
 <tr><td> ReferenceMany(targetDocument="myDocument", weak=false): </td><td>Same as ReferenceOne except that you can refer many documents with the same document and reference type. If you dont't specify targetDocument you can reference different documents with one property.</td></tr>
267 267
 <tr><td> Referrers(filter="x", referenceType=null):     </td><td>A field of this type stores documents that refer this document. filter is optional. Its value is passed to the name parameter of <a href="http://phpcr.github.com/doc/html/phpcr/nodeinterface.html#getWeakReferences%28%29">Node::getReferences()<a/> or <a href="http://phpcr.github.com/doc/html/phpcr/nodeinterface.html#getWeakReferences%28%29">Node::getWeakReferences()</a>. You can also specify an optional referenceType, weak or hard, to only get documents that have either a weak or a hard reference to this document. If you specify null then all documents with weak or hard references are fetched, which is also the default behavior.</td></tr>
  268
+<tr><td>Locale</td><td>Indentifies the field that will be used to store the current locale of the document. This annotation is required for translatable documents.</td></tr>
268 269
 <tr><td> String,               <br />
269 270
          Binary,               <br />
270 271
          Long (alias Int),     <br />
@@ -293,6 +294,164 @@ private $cat;
293 294
 
294 295
 Note that the reference annotations are only possible if your PHPCR implementation supports programmatically setting the uuid property at node creation.
295 296
 
  297
+# Multilingual documents
  298
+
  299
+PHPCR-ODM supports multilingual documents so that you can mark properties as translatable and then make the document manager automatically store the translations.
  300
+
  301
+To use translatable documents you need to use several annotations and some bootstrapping code.
  302
+
  303
+```php
  304
+<?php
  305
+use Doctrine\ODM\PHPCR\Mapping\Annotations as PHPCRODM;
  306
+
  307
+/**
  308
+ * @PHPCRODM\Document(alias="translation_article", translator="attribute")
  309
+ */
  310
+class Article
  311
+{
  312
+    /** @PHPCRODM\Id */
  313
+    public $id;
  314
+
  315
+    /**
  316
+     * @PHPCRODM\Locale
  317
+     */
  318
+    public $locale = 'en';
  319
+
  320
+    // untranslated:
  321
+    /** @PHPCRODM\Date */
  322
+    public $publishDate;
  323
+
  324
+    // untranslated:
  325
+    /** @PHPCRODM\String */
  326
+    public $author;
  327
+
  328
+    /** @PHPCRODM\String(translated=true) */
  329
+    public $topic;
  330
+
  331
+    /** @PHPCRODM\String(translated=true) */
  332
+    public $text;
  333
+}
  334
+```
  335
+
  336
+## Select the translation strategy
  337
+
  338
+A translation strategy needs to be selected by adding the `translator` parameter to the @Document annotation.
  339
+The translation strategy is responsible to actually persist the translated properties.
  340
+
  341
+There are two translation strategies implemented:
  342
+
  343
+* **attribute** - will store the translations in attributes of the node containing the translatable properties
  344
+* **child** - will store the translations in a child node of the node containing the translatable properties
  345
+
  346
+It is possible to implement other strategies to persist the translations, see below.
  347
+
  348
+### Implementing your own translation strategy
  349
+
  350
+You may want to implement your own translation strategy to persist the translatable properties of a node. For example if you want all the translations to be stored in a separate branch of you content repository.
  351
+
  352
+To do so you need to implement the `Doctrine\ODM\PHPCR\Translation\TranslationStrategy\TranslationStrategyInterface`.
  353
+
  354
+Then you have to register your translation strategy with the document manager during the bootstrap.
  355
+
  356
+```php
  357
+<?php
  358
+class MyTranslationStrategy implements Doctrine\ODM\PHPCR\Translation\TranslationStrategy\TranslationStrategyInterface
  359
+{
  360
+    // ...
  361
+}
  362
+
  363
+$dm = new \Doctrine\ODM\PHPCR\DocumentManager($session, $config);
  364
+$dm->setTranslationStrategy('my_strategy_name', new MyTranslationStrategy());
  365
+```
  366
+
  367
+After registering your new translation strategy you can use it in the @Document annotation:
  368
+
  369
+```php
  370
+<?php
  371
+/**
  372
+ * @PHPCRODM\Document(alias="translation_article", translator="my_strategy_name")
  373
+ */
  374
+class Article
  375
+{
  376
+    // ...
  377
+}
  378
+```
  379
+
  380
+## Select the language chooser strategy
  381
+
  382
+The language chooser strategy is responsible to return a the locale to use when a document is requested in a given language.
  383
+
  384
+Typically the default language chooser strategy (`Doctrine\ODM\PHPCR\Translation\LocaleChooser`) will return the requested language if there are translations for it, or else perform some fallback mechanism to find the best suited locale.
  385
+
  386
+You always have to select the language chooser when you bootstrap the document manager:
  387
+
  388
+```php
  389
+<?php
  390
+$localePrefs = array(
  391
+    'en' => array('en', 'de', 'fr'), // When EN is requested try to get a translation first in EN, then DE and finally FR
  392
+    'fr' => array('fr', 'de', 'en'), // When FR is requested try to get a translation first in FR, then DE and finally EN
  393
+    'it' => array('fr', 'de', 'en'), // When IT is requested try to get a translation first in FR, then DE and finally EN
  394
+);
  395
+
  396
+$dm = new \Doctrine\ODM\PHPCR\DocumentManager($session, $config);
  397
+$dm->setLocaleChooserStrategy(new LocaleChooser($localePrefs, 'en'));
  398
+```
  399
+
  400
+At the end of this language selection phase, if no translation for any of the returned languages can be found, an exception is thrown.
  401
+
  402
+## Mark a field as @Locale
  403
+
  404
+All the translatable documents (i.e. having at least one translatable field) must define a field that will hold the current locale of the node.
  405
+This is done with the `@Locale` annotation. You may set a default value.
  406
+
  407
+```php
  408
+<?php
  409
+/**
  410
+ * @PHPCRODM\Locale
  411
+ */
  412
+public $locale = 'en';
  413
+```
  414
+
  415
+This field is __mandatory__ and is not persisted to the content repository.
  416
+
  417
+## Setting properties as translatable
  418
+
  419
+A property is set as translatable adding the `translatable` parameter to the field definition annontation.
  420
+
  421
+```php
  422
+<?php
  423
+/** @PHPCRODM\String(translated=true) */
  424
+public $topic;
  425
+```
  426
+
  427
+You can set any type of property as translatable.
  428
+
  429
+Having a single property set as translatable will make the whole document translatable and thus forces you to have a @Locale field (see above).
  430
+
  431
+Please note that internally, the translatable properties will be persisted by the translator strategy, not directly by the document manager.
  432
+
  433
+## Translation API
  434
+
  435
+TODO: just refer to the phpdoc...
  436
+
  437
+__For reading__:
  438
+
  439
+* `DocumentManager::find(...)` - Will load the document from the content repository. If the document is translatable then the language chooser strategy is used to load the best suited language for the translatable fields.
  440
+* `DocumentManager::findTranslation(..., $locale, $fallback = true)` - Will try to load the document in the given language. If not possible and $fallback is true then the language chooser mechanism is used to find the best language. Otherwise an error is thrown. Note that this will be the same object as you got with a previous find/findTranslation call - we can't allow copies of objects to exist or it will confuse the hell out of phpcr-odm.
  441
+
  442
+Both the above functions will update the document field set as @Locale.
  443
+
  444
+__For writing__:
  445
+
  446
+* DocumentManager::persist()
  447
+* DocumentManager::flush()
  448
+* DocumentManager::persitTranslation()
  449
+
  450
+## Example
  451
+
  452
+```php
  453
+<?php
  454
+```
296 455
 
297 456
 # Lifecycle callbacks
298 457
 

0 notes on commit 7998ed3

Please sign in to comment.
Something went wrong with that request. Please try again.