Merge pull request #5190 from coudenysj/translation-documentation

Merge the translation component documentation in the resource component documentation

docs/components/Attribute/models.rst

@@ -31,7 +31,7 @@ Every attribute is represented by the **Attribute** model which by default has t
 +---------------+-----------------------------------------------------------+
 
 .. note::
-   This model extends the :ref:`component_translation_model_abstract-translatable` class
+   This model uses the :ref:`component_resource_translations_translatable-trait`
    and implements the :ref:`component_attribute_model_attribute-interface`.
 
    For more detailed information go to `Sylius API Attribute`_.
@@ -101,7 +101,7 @@ model which has the following properties:
 +-----------+----------------------------------------+
 
 .. note::
-   This model extends the :ref:`component_translation_model_abstract-translation` class
+   This model extends the :ref:`component_resource_translations_abstract-translation` class
    and implements the :ref:`component_attribute_model_attribute-translation-interface`.
 
    For more detailed information go to `Sylius API AttributeTranslation`_.

docs/components/Product/models.rst

@@ -40,7 +40,7 @@ By default it contains the following properties:
 +-----------------+-----------------------------------------------------------------------------+
 
 .. note::
-   This model extends the :ref:`component_translation_model_abstract-translatable`
+   This model uses the :ref:`component_resource_translations_translatable-trait`
    and implements the :ref:`component_product_model_product-interface`.
 
    For more detailed information go to `Sylius API Product`_.
@@ -63,7 +63,7 @@ By default it has the following properties:
 +-----------------+--------------------------------------+
 
 .. note::
-   This model extends the :ref:`component_translation_model_abstract-translation`
+   This model extends the :ref:`component_resource_translations_abstract-translation` class
    and implements the :ref:`component_product_model_product-translation-interface`.
 
    For more detailed information go to `Sylius API ProductTranslation`_.

docs/components/Resource/index.rst

@@ -10,4 +10,6 @@ Domain management abstraction for PHP. It provides interface for most common ope
    model
    factory
    repository
+   service
+   translation
    summary

docs/components/Resource/model.rst

@@ -83,3 +83,35 @@ and will ask you to implement the following methods to your model:
 +------------------------------------+------------------------------------------+-------------------+
 | setSlug(string $slug = null)       | Set slug                                 | void              |
 +------------------------------------+------------------------------------------+-------------------+
+
+.. _component_resource_model_translatable-interface:
+
+TranslatableInterface
+---------------------
+
+This interface should be implemented by a model used in more than one language.
+
+.. hint::
+   Although you can implement this interface in your class, it's easier to just
+   use the :ref:`component_resource_translations_translatable-trait` class.
+
+.. note::
+   For more detailed information go to `Sylius API TranslatableInterface`_.
+
+.. _Sylius API TranslatableInterface: http://api.sylius.org/Sylius/Component/Resource/Model/TranslatableInterface.html
+
+.. _component_resource_model_translation-interface:
+
+TranslationInterface
+--------------------
+
+This interface should be implemented by a model responsible for keeping a single translation.
+
+.. hint::
+   And as above, although you are completely free to create your own class implementing this interface,
+   it's already implemented in the :ref:`component_resource_translations_abstract-translation` class.
+
+.. note::
+   For more detailed information go to `Sylius API TranslationInterface`_.
+
+.. _Sylius API TranslationInterface: http://api.sylius.org/Sylius/Component/Resource/Model/TranslationInterface.html

docs/components/Resource/service.rst

@@ -0,0 +1,32 @@
+Service interfaces
+==================
+
+.. _component_resource_provider_locale-provider-interface:
+
+LocaleProviderInterface
+-----------------------
+
+This interface should be implemented by a service responsible for managing locales.
+
+.. note::
+   For more detailed information go to `Sylius API LocaleProviderInterface`_.
+
+.. _Sylius API LocaleProviderInterface: http://api.sylius.org/Sylius/Component/Resource/Provider/LocaleProviderInterface.html
+
+.. _component_resource_repository_translatable-resource-repository-interface:
+
+TranslatableRepositoryInterface
+-------------------------------
+
+This interface should be implemented by a repository responsible for keeping the **LocaleProvider**
+and an array of fields
+
+This interface expects you to implement a way of setting an instance of **LocaleProviderInterface**,
+and an array of translatable fields into your custom repository.
+
+.. note::
+   This interface extends the :ref:`component_resource_repository_repository-interface`.
+
+   For more detailed information go to `Sylius API TranslatableResourceRepositoryInterface`_.
+
+.. _Sylius API TranslatableResourceRepositoryInterface: http://api.sylius.org/Sylius/Component/Resource/Repository/TranslatableRepositoryInterface.html

docs/components/Translation/basic_usage.rst → docs/components/Resource/translation.rst

@@ -1,7 +1,7 @@
-Basic Usage
-===========
+Translations
+============
 
-.. _book-translation:
+.. _component_resource_translations_abstract-translation:
 
 Implementing AbstractTranslation
 --------------------------------
@@ -14,7 +14,7 @@ First let's create a class which will keep our translatable properties:
 
    namespace Example\Model;
 
-   use Sylius\Component\Translation\Model\AbstractTranslation;
+   use Sylius\Component\Resource\Model\AbstractTranslation;
 
    class BookTranslation extends AbstractTranslation
    {
@@ -40,10 +40,10 @@ First let's create a class which will keep our translatable properties:
        }
    }
 
-.. _book:
+.. _component_resource_translations_translatable-trait:
 
-Implementing AbstractTranslatable
----------------------------------
+Using TranslatableTrait
+-----------------------
 
 Now the following class will be actually capable of translating the **title**:
 
@@ -53,10 +53,13 @@ Now the following class will be actually capable of translating the **title**:
 
    namespace Example\Model;
 
-   use Sylius\Component\Translation\Model\AbstractTranslatable;
+   use Sylius\Component\Resource\Model\TranslatableInterface;
+   use Sylius\Component\Resource\Model\TranslatableTrait;
 
-   class Book extends AbstractTranslatable
+   class Book implements TranslatableInterface
    {
+       use TranslatableTrait;
+
        /**
         * @return string
         */
@@ -78,12 +81,12 @@ Now the following class will be actually capable of translating the **title**:
    As you could notice, inside both methods we use the ``translate`` method.
    More specified explanation on what it does is described further on.
 
-.. _component_translation_basic-translations:
+.. _component_resource_translations_usage:
 
 Using Translations
 ------------------
 
-Once we have both abstract classes implemented we can start translating.
+Once we have both classes implemented we can start translating.
 So first we need to create a few instances of our translation class:
 
 .. code-block:: php
@@ -153,23 +156,23 @@ You can always use the ``translate`` method by itself, but the same principal is
 
 .. _\\RuntimeException: https://secure.php.net/manual/pl/class.runtimeexception.php
 
-.. _component_translation_provider_locale-provider:
+.. _component_resource_provider_locale-provider:
 
 LocaleProvider
 --------------
 
 This service provides you with an easy way of managing locales.
 The first parameter set in it's constructor is the current locale and the second, fallback.
 
-In this example let's use the provider with our :ref:`Book <book>`
-class which extends the :ref:`component_translation_model_abstract-translatable`:
+In this example let's use the provider with our `Book`
+class which uses the :ref:`component_resource_translations_translatable-trait`:
 
 .. code-block:: php
 
    <?php
 
    use Example\Model\Book;
-   use Sylius\Component\Translation\Provider\LocaleProvider;
+   use Sylius\Component\Resource\Provider\LocaleProvider;
 
    $provider = new LocaleProvider('de', 'en');
 
@@ -181,15 +184,15 @@ class which extends the :ref:`component_translation_model_abstract-translatable`
    $book->getCurrentLocale(); // returns 'de'
    $book->getFallbackLocale(); // returns 'en'
 
-... and with an :ref:`component_translation_model_abstract-translation`
-class such as the exemplary :ref:`BookTranslation <book-translation>` it goes:
+... and with an :ref:`component_resource_translations_abstract-translation`
+class such as the exemplary `BookTranslation` it goes:
 
 .. code-block:: php
 
    <?php
 
    use Example\Model\BookTranslation;
-   use Sylius\Component\Translation\Provider\LocaleProvider;
+   use Sylius\Component\Resource\Provider\LocaleProvider;
 
    $provider = new LocaleProvider('de', 'en');
 
@@ -200,4 +203,4 @@ class such as the exemplary :ref:`BookTranslation <book-translation>` it goes:
    $translation->getLocale(); // returns 'de'
 
 .. note::
-   This service implements the :ref:`component_translation_provider_locale-provider-interface`.
+   This service implements the :ref:`component_resource_provider_locale-provider-interface`.

docs/components/Shipping/basic_usage.rst

@@ -182,7 +182,7 @@ Shipping Method Translation
 ---------------------------
 
 **ShippingMethodTranslation** allows shipping method's name translation according to given locales. To see how to use translation
-please go to :ref:`component_translation_basic-translations`.
+please go to :ref:`component_resource_translations_usage`.
 
 Rule
 ----

docs/components/Shipping/models.rst

@@ -136,8 +136,8 @@ It has the following properties:
 +---------------------+-------------------------------------------------------------------------+
 
 .. note::
-    This model implements the :ref:`component_shipping_model_shipping-method-interface` and extends
-    :ref:`component_translation_model_abstract-translatable` class.
+    This model implements the :ref:`component_shipping_model_shipping-method-interface` and uses the
+    :ref:`component_resource_translations_translatable-trait`.
 
     For more detailed information go to `Sylius API ShippingMethod`_.
 
@@ -163,7 +163,7 @@ It has the following properties:
 
 .. note::
     This model implements the :ref:`component_shipping_model_shipping-method-translation-interface` and extends
-    :ref:`component_translation_model_abstract-translation` class.
+    :ref:`component_resource_translations_abstract-translation` class.
 
     Form more information go to `Sylius API ShippingMethodTranslation`_.
 

docs/components/Taxonomy/interfaces.rst

@@ -14,7 +14,7 @@ The **TaxonInterface** gives an object an ability to have Taxons assigned as chi
 .. note::
 
     This interface extends the :ref:`component_resource_model_code-aware-interface`,
-    :ref:`component_translation_model_translatable-interface`
+    :ref:`component_resource_model_translatable-interface`
     and the :ref:`component_taxonomy_model_taxon-translation-interface`.
 
     You will find more information about that interface in `Sylius API TaxonInterface`_.