php-translation · cyprianmeister · Dec 26, 2016 · Dec 27, 2016 · Dec 27, 2016 · Jan 3, 2017
diff --git a/.travis.yml b/.travis.yml
@@ -4,6 +4,10 @@ addons:
     apt_packages:
         - enchant
 
+branches:
+  except:
+    - /^patch-.*$/
+
 install:
     - pip install --user -r requirements.txt
 

diff --git a/assets/image/demo-html-editor.png b/assets/image/demo-html-editor.png
diff --git a/assets/image/edit-in-place-demo.gif b/assets/image/edit-in-place-demo.gif
diff --git a/best-practice/index.rst b/best-practice/index.rst
@@ -36,9 +36,10 @@ they are used. The following table is a good rule of thumb.
    "**error.** foo", "For error messages."
    "**help.** foo", "For help text used with forms."
    "foo **.heading**", "For a heading."
-   "foo **.pragraph0**", "For the first paragraph after a heading."
-   "foo **.pragraph1**", "For the second paragraph after a heading."
-   "_foo", "Starting with underscore means the the translated string should start with a lowercase letter."
+   "foo **.paragraph0**", "For the first paragraph after a heading."
+   "foo **.paragraph1**", "For the second paragraph after a heading."
+   "foo.paragraph2 **.html**", "A third paragraph where HTML is allowed inside the translation."
+   "_foo", "Starting with underscore means the the translated string should start with a lowercase character."
    "**foo**", "For any common strings like “Show all”, “Next”, “Yes” etc."
    "**vendor.bundle.controller.action.** foo", "For any non-reusable translation."
 

diff --git a/components/cli.rst b/components/cli.rst
@@ -0,0 +1,48 @@
+Command line interface
+======================
+
+If you do not want to "pollute" your application with a lot of dependencies you may
+install our CLI tool. It is basically the Symfony Translation bundle packed down in
+a single PHAR.
+
+The CLI support extracting, syncing and downloading translations. It does also run
+the WebUI so you can edit translations in a nice user interface.
+
+Download
+--------
+
+.. code-block:: bash
+
+    wget https://php-translation.github.io/cli/downloads/translation.phar
+    chmod +x translation.phar
+
+
+Configuration
+-------------
+
+Every time you run the CLI it looks for a configuration file named "translation.yml"
+that should be located in the same directory that you execute the command. The
+configuration will be exact the same as for the TranslationBundle. Example:
+
+.. code-block:: yaml
+
+    # translation.yml
+    translation:
+      locales: ["en", "sv"]
+      configs:
+        app:
+          dirs: ["%kernel.project_dir%/app/Resources/views", "%kernel.project_dir%/src"]
+          output_dir: "%kernel.project_dir%/app/Resources/translations"
+          excluded_names: ["*TestCase.php", "*Test.php"]
+          excluded_dirs: [cache, data, logs]
+
+
+Other translation bundles installed
+-----------------------------------
+
+The CLI tool does also have a few other translation bundles installed. They are installed
+by default to give you the possibility to configure different kind of remote storages.
+
+* Loco Adapter
+* Flysystem Adapter
+* Phraseapp Adapter
diff --git a/components/extractor.rst b/components/extractor.rst
@@ -39,7 +39,7 @@ When the extractor is downloaded you may use it by doing the following:
 
     // Print the result
     foreach ($sourceCollection as $source) {
-      echo sprintf('Key "%s" found in %s at line %d', $source-getMessage(), $source->getPath(), $source->getLine());
+      echo sprintf('Key "%s" found in %s at line %d', $source->getMessage(), $source->getPath(), $source->getLine());
     }
 
 Architecture
@@ -79,6 +79,34 @@ will be returned.
     If you want to add functionality to the extractor you are most likely to add
     a new visitor. See :doc:`../guides/adding-extractor` for more information.
 
+Special extractors
+------------------
+
+We have common extractors for Symfony, Twig and Blade. They all are doing static
+analysis on the source files to find translation strings. But in some situations
+you need to specify translation dynamically. You may achieve this by implementing
+``TranslationSourceLocationContainer``.
+
+.. code-block:: php
+
+    use Translation\Extractor\Model\SourceLocation;
+    use Translation\Extractor\TranslationSourceLocationContainer;
+    use Symfony\Component\Form\AbstractType;
+
+    class MyCustomFormType extends AbstractType implements TranslationSourceLocationContainer
+    {
+        // ...
+        public static function getTranslationSourceLocations()
+        {
+            $options = // Get options
+            $data = [];
+            foreach ($options as $option) {
+                $data[] = SourceLocation::createHere('option.'.$option);
+            }
+
+            return $data;
+        }
+    }
 
 
 .. _`Visitor pattern`: https://en.wikipedia.org/wiki/Visitor_pattern

diff --git a/components/platform-adapters.rst b/components/platform-adapters.rst
diff --git a/components/translator.rst b/components/translator.rst
@@ -7,7 +7,7 @@ Translate or Bing Translate.
 Installation and Usage
 ----------------------
 
-Install the extractor component with Composer
+Install the translator component with Composer
 
 .. code-block:: bash
 

diff --git a/guides/configure-httplug.rst b/guides/configure-httplug.rst
@@ -48,7 +48,7 @@ and a PSR-6 cache pool.
                 cache_pool: 'cache.provider.my_redis'
                 config:
                     default_ttl: 94608000 # three years
-                    respect_cache_headers: false # We cache no matter what the sever says
+                    respect_cache_headers: false # We cache no matter what the server says
         clients:
             translator_client:
                 factory: 'httplug.factory.guzzle6'
@@ -58,7 +58,7 @@ and a PSR-6 cache pool.
         # ...
         http_client: 'httplug.client.translator_client'
         fallback_translation:
-            service: 'google'
+            service: 'google' # 'yandex' is available as an alternative
             api_key: 'foobar'
 
 .. note::

diff --git a/guides/using-loco-adapter.rst b/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 enabled.
 
 .. code-block:: php
 
@@ -47,8 +47,8 @@ Loco the configuration looks like this:
         navigation:
           api_key: 'bazbar'
 
-When the platform adapter bundle is configured it will register a service with id
-`php_translation.adapter.loco`. Now wee need to tell the ``TranslationBundle``
+When the storage adapter bundle is configured it will register a service with id
+`php_translation.adapter.loco`. Now we need to tell the ``TranslationBundle``
 to use this adapter.
 
 .. note::

diff --git a/index.rst b/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:
@@ -97,6 +57,7 @@ They all live in the php-translation/platform-adapter repository.
    Symfony Profiler UI <symfony/profiler-ui>
    Edit in place <symfony/edit-in-place>
    Auto translate <symfony/auto-translate>
+   Auto add missing translations <symfony/auto-add-missing>
 
 .. toctree::
    :hidden:
@@ -105,8 +66,7 @@ They all live in the php-translation/platform-adapter repository.
    Common <components/common>
    Extractor <components/extractor>
    Translator <components/translator>
-   Platform adapters <components/platform-adapters>
-
+   CLI <components/cli>
 
 
 .. toctree::

diff --git a/introduction.rst b/introduction.rst