Update docs, intro and overview

guides/using-loco-adapter.rst

@@ -3,20 +3,20 @@ How to use Loco Adapter
 
 When your application has reached a certain number of languages and you can't translate
 all of them yourself you need a translation platform to ease your work with external
-translators. This article shows how to set up a platform adapter using Loco_. Loco
-is just an example here. All platform adapters have a similar way of being configured.
+translators. This article shows how to set up a storage adapter using Loco_. Loco
+is just an example here. All storage adapters have a similar way of being configured.
 
 Installation
 ------------
 
 Assuming you have already installed the :doc:`Symfony bundle <../symfony/index>`,
-you need to find and install the platform adapter. See our :doc:`list of adapters <../components/platform-adapters>`.
+you need to find and install a storage adapter. See our :doc:`list of storage adapters <../overview>`.
 
 .. code-block:: bash
 
     composer require php-translation/loco-adapter
 
-The platform adapter does also contain a bundle which needs to be installed.
+The storage adapter does also contain a bundle which needs to be installed.
 
 .. code-block:: php
 
@@ -47,7 +47,7 @@ Loco the configuration looks like this:
         navigation:
           api_key: 'bazbar'
 
-When the platform adapter bundle is configured it will register a service with id
+When the storage adapter bundle is configured it will register a service with id
 `php_translation.adapter.loco`. Now wee need to tell the ``TranslationBundle``
 to use this adapter.
 

index.rst

@@ -1,82 +1,42 @@
 PHP Translation
 ===============
 
-The goal of this organization is to provide a tool set for doing translations in
-a PHP project. The secondary goal is to provide guides or case studies how one
-could use those tools.
+**How do you manage your multilanguage Symfony application?**
 
-Organization overview
----------------------
+This is something you know many companies do but nobody talks about how they do it.
+It might be because nobody is really proud of their solution. That is something we
+like to change. We want to share ideas, knowledge and tools with the PHP community.
 
-Extractor
-`````````
-.. image:: https://poser.pugx.org/php-translation/extractor/v/stable
-   :target: https://packagist.org/packages/php-translation/extractor
+This organization has some large building blocks that you should be aware of. First
+there is the :doc:`Extractor<components/extractor>` that finds translation keys in
+any source file. Second we have the :doc:`Symfony Bundle<symfony/index>` which is
+using the Extractor and puts a lot of great feature that will help your translation
+workflow. There are features like :doc:`automatic translation<symfony/auto-translate>`, a
+:doc:`Web UI<symfony/webui>`, :doc:`Edit-in-place<symfony/edit-in-place>`
+that allows you to edit translations in the right context and there is also support
+for multiple local and remote *storages*.
 
-.. image:: https://poser.pugx.org/php-translation/extractor/downloads
-   :target: https://packagist.org/packages/php-translation/extractor
-   :alt: Total Downloads
+Getting started
+---------------
 
-This package include extractors that look at your source code and extract translation
-keys from it. We support extractor from PHP files, Twig files and Blade template
-files.
-
-Common
-``````
-.. image:: https://poser.pugx.org/php-translation/common/v/stable
-   :target: https://packagist.org/packages/php-translation/common
-
-.. image:: https://poser.pugx.org/php-translation/common/downloads
-   :target: https://packagist.org/packages/php-translation/common
-   :alt: Total Downloads
-
-Common interfaces and classes used by 2 or more packages.
-
-Translator
-``````````
-.. image:: https://poser.pugx.org/php-translation/translator/v/stable
-   :target: https://packagist.org/packages/php-translation/translator
-
-.. image:: https://poser.pugx.org/php-translation/translator/downloads
-   :target: https://packagist.org/packages/php-translation/translator
-   :alt: Total Downloads
-
-The translator package includes third party translation clients. Use this package
-if you want to translate a string with Google Translate or Bing Translate.
-
-Symfony Bundle
-``````````````
-.. image:: https://poser.pugx.org/php-translation/symfony-bundle/v/stable
-   :target: https://packagist.org/packages/php-translation/symfony-bundle
-
-.. image:: https://poser.pugx.org/php-translation/symfony-bundle/downloads
-   :target: https://packagist.org/packages/php-translation/symfony-bundle
-   :alt: Total Downloads
-
-The Symfony bundle integrates all these fancy features with Symfony. We have support
-for automatic translation, web UI, third party services and more.
-
-
-Platform adapters
-`````````````````
-
-This organisation has plenty of platform adapters to support third party services.
-They all live in the php-translation/platform-adapter repository.
+If you are using Symfony you should start by looking at the documentation for the
+:doc:`Symfony bundle<symfony/index>`. If you are more hard core you may want to
+start by looking at the :doc:`overview`.
 
 
 .. toctree::
     :hidden:
 
     PHP Translation <self>
-    Introduction <introduction>
+    Organization overview <overview>
 
 .. toctree::
    :hidden:
    :caption: Guides
 
-   Adding extractors <guides/adding-extractor>
-   Configure Platform adapter <guides/using-loco-adapter>
+   Configure storage adapter <guides/using-loco-adapter>
    Configure HTTPlug <guides/configure-httplug>
+   Adding extractors <guides/adding-extractor>
 
 .. toctree::
    :hidden:
@@ -106,8 +66,6 @@ They all live in the php-translation/platform-adapter repository.
    Common <components/common>
    Extractor <components/extractor>
    Translator <components/translator>
-   Platform adapters <components/platform-adapters>
-
 
 
 .. toctree::

overview.rst

@@ -0,0 +1,120 @@
+Organization overview
+=====================
+
+There is quite a few repositories in this organisation. Here is a brief overview
+what all of them does.
+
+Extractor
+---------
+.. image:: https://poser.pugx.org/php-translation/extractor/v/stable
+   :target: https://github.com/php-translation/extractor
+
+.. image:: https://poser.pugx.org/php-translation/extractor/downloads
+   :target: https://packagist.org/packages/php-translation/extractor
+   :alt: Total Downloads
+
+This package include extractors that look at your source code and extract translation
+keys from it. We support extractor from PHP files, Twig files and Blade template
+files. Read more :doc:`about the extractor <components/extractor>`.
+
+Common
+------
+.. image:: https://poser.pugx.org/php-translation/common/v/stable
+   :target: https://github.com/php-translation/common
+
+.. image:: https://poser.pugx.org/php-translation/common/downloads
+   :target: https://packagist.org/packages/php-translation/common
+   :alt: Total Downloads
+
+Common interfaces and classes used by 2 or more packages. Read more
+:doc:`about common <components/common>`.
+
+Symfony Bundle
+--------------
+.. image:: https://poser.pugx.org/php-translation/symfony-bundle/v/stable
+   :target: https://github.com/php-translation/symfony-bundle
+
+.. image:: https://poser.pugx.org/php-translation/symfony-bundle/downloads
+   :target: https://packagist.org/packages/php-translation/symfony-bundle
+   :alt: Total Downloads
+
+The Symfony bundle integrates all these fancy features with Symfony. We have support
+for automatic translation, web UI, third party services and more. Read more
+:doc:`about the bundle <symfony/index>`.
+
+
+Translator
+----------
+.. image:: https://poser.pugx.org/php-translation/translator/v/stable
+   :target: https://github.com/php-translation/translator
+
+.. image:: https://poser.pugx.org/php-translation/translator/downloads
+   :target: https://packagist.org/packages/php-translation/translator
+   :alt: Total Downloads
+
+The translator package includes third party translation clients. Use this package
+if you want to translate a string with Google Translate or Bing Translate.
+Read more :doc:`about translators <components/translator>`.
+
+Storage adapters
+----------------
+
+This organisation has plenty of storage adapters to support storing your translations
+on different third party services. All storages implement ``Translation\Common\Storage``.
+The Symfony bundle allows you to use multiple storages.
+
+Symfony storage
+```````````````
+.. image:: https://poser.pugx.org/php-translation/symfony-storage/v/stable
+   :target: https://github.com/php-translation/symfony-storage
+
+.. image:: https://poser.pugx.org/php-translation/symfony-storage/downloads
+   :target: https://packagist.org/packages/php-translation/symfony-storage
+   :alt: Total Downloads
+
+The Symfony storage stores translations on the local file system using Symfony's
+writers and loaders. This storage is required by the Symfony bundle and should be
+considered as a "local cache".
+
+The Symfony storage also has a ``XliffConverter`` that converts a ``Catalogue`` to
+the contents of a Xliff file. It also supports the reverse action.
+
+Flysystem
+`````````
+.. image:: https://poser.pugx.org/php-translation/flysystem-adapter/v/stable
+   :target: https://github.com/php-translation/flysystem-adapter
+
+.. image:: https://poser.pugx.org/php-translation/flysystem-adapter/downloads
+   :target: https://packagist.org/packages/php-translation/flysystem-adapter
+   :alt: Total Downloads
+
+Do you use a remote filesystem for your translations? The Flysystem adapter is the
+adapter for you. It is a storage based on the excellent Flysystem_ by Frank de Jonge.
+
+Loco
+````
+.. image:: https://poser.pugx.org/php-translation/loco-adapter/v/stable
+   :target: https://github.com/php-translation/loco-adapter
+
+.. image:: https://poser.pugx.org/php-translation/loco-adapter/downloads
+   :target: https://packagist.org/packages/php-translation/loco-adapter
+   :alt: Total Downloads
+
+Use the power of Loco_ to manage your translations and give your translators access
+to a custom user interface. Loco is created by Tim Withlock.
+
+Transifex
+`````````
+.. image:: https://poser.pugx.org/php-translation/transifex-adapter/v/stable
+   :target: https://github.com/php-translation/transifex-adapter
+
+.. image:: https://poser.pugx.org/php-translation/transifex-adapter/downloads
+   :target: https://packagist.org/packages/php-translation/transifex-adapter
+   :alt: Total Downloads
+
+An adapter for Transifex_.
+
+
+.. _`Flysystem`: https://flysystem.thephpleague.com/
+.. _`Loco`: https://localise.biz/
+.. _`Transifex`: https://www.transifex.com/

spelling_word_list.txt

@@ -1,7 +1,11 @@
 backtrace
 Bing
+de
+Flysystem
+filesystem
 Google
 hotfix
+Jonge
 Nikic
 organisation
 practises
@@ -14,6 +18,9 @@ sexualized
 storages
 sublicense
 Symfony
+Transifex
 username
 wiki
+Withlock
 workflow
+Xliff

symfony/index.rst

@@ -92,5 +92,5 @@ must implement `Translation\Common\Storage`.
           local_storage: ["app.custom_local_storage"]
 
 The PHP Translation organisation provides some adapters to commonly used translation
-platforms. See our all :doc:`platform adapters <../components/platform-adapters>`
+storages. See our all :doc:`storage adapters <../overview>`
 or see an example on how to :doc:`install an adapter <../guides/using-loco-adapter>`.