diff --git a/CONTRIBUTING b/CONTRIBUTING index 841914a..870220f 100644 --- a/CONTRIBUTING +++ b/CONTRIBUTING @@ -1 +1 @@ -Please see http://docs.php-http.org/en/latest/development/contributing.html +Please see http://php-translation.readthedocs.io/en/latest/development/contributing.html diff --git a/_static/custom.css b/_static/custom.css index ed3b698..45815eb 100644 --- a/_static/custom.css +++ b/_static/custom.css @@ -10,6 +10,7 @@ color: #b3b3b3; margin-top: 16px; margin-bottom: 0; + margin-left: 1.4em } .wy-menu-vertical p.caption .caption-text { font-size: 120%; diff --git a/assets/image/webui-dashboard.png b/assets/image/webui-dashboard.png new file mode 100644 index 0000000..31d4b18 Binary files /dev/null and b/assets/image/webui-dashboard.png differ diff --git a/assets/image/webui-page.png b/assets/image/webui-page.png new file mode 100644 index 0000000..f4d8bb5 Binary files /dev/null and b/assets/image/webui-page.png differ diff --git a/components/common.rst b/components/common.rst new file mode 100644 index 0000000..836db4e --- /dev/null +++ b/components/common.rst @@ -0,0 +1,29 @@ +Common +====== + +The Common component is the least exiting component. It contains common interfaces +and classes that are used by many other packages in this organization. The most +important ones are listed on this page. + +Message +------- + +The ``Message`` class is a representation of a translation in a specific language. This +class is commonly used as a parameter or a return value for functions in the organisation. + +The message contains of an ``key``, ``domain``, ``locale`` and ``translation``. +There is also an array where meta data can be stored. Example of usage of meta data +could be when a third party translation service has flagged the translation as "fuzzy". + +Storage +------- + +The ``Storage`` interface is an abstraction for places where you can store translations. +There are many examples like on file system, in database or in any third party translation +service. A ``Storage`` is very simple. It has methods for getting, updating and +deleting a translation. + +Exception +--------- + +The ``Exception`` interface will decorate all the runtime exceptions in the organisation. diff --git a/components/extractor.rst b/components/extractor.rst new file mode 100644 index 0000000..b2a5b96 --- /dev/null +++ b/components/extractor.rst @@ -0,0 +1,86 @@ +Extractor +========= + +The responsibility of the Extractor component is to get translation keys from the +source code. + +Installation and Usage +---------------------- + +Install the extractor component with Composer + +.. code-block:: bash + + composer require php-translation/extractor + +When the extractor is downloaded you may use it by doing the following: + +.. code-block:: php + + require "vendor/autoload.php"; + + use Translation\Extractor\Visitor\Php\Symfony as Visitor; + + // Create extractor for PHP files + $fileExtractor = new PHPFileExtractor() + + // Add visitors + $fileExtractor->addVisitor(new Visitor\ContainerAwareTrans()); + $fileExtractor->addVisitor(new Visitor\ContainerAwareTransChoice()); + $fileExtractor->addVisitor(new Visitor\FlashMessage()); + $fileExtractor->addVisitor(new Visitor\FormTypeChoices()); + + // Add the file extractor to Extractor + $extractor = new Extractor(); + $extractor->addFileExtractor($this->getPHPFileExtractor()); + + //Start extracting files + $sourceCollection = $extractor->extractFromDirectory('/foo/bar'); + + // Print the result + foreach ($sourceCollection as $source) { + echo sprintf('Key "%s" found in %s at line %d', $source-getMessage(), $source->getPath(), $source->getLine()); + } + +Architecture +------------ + +There is a lot of things happening the the code example above. Everything is very +SOLID so it is easy to add your own extractors if you have custom features that +you need to translate. + +The class that we interact with after when we want to extract translations is the +``Extractor`` class. It supports ``Extractor::extractFromDirectory(string)`` and +the more flexible ``Extractor::extract(Finder)``. The Extractor looks at all files +in the directory and checks the type/extension. The extractor then executes all +``FileExtractor`` for this file type. + +There is a few ``FileExtractor`` that comes with this component. They are ``PHPFileExtractor``, +``TwigFileExtractor`` and ``BladeExtractor``. As you may guess they extract translations +from PHP files, Twig files and Blade files respectively. The most interesting ones +are ``PHPFileExtractor`` and ``TwigFileExtractor`` because they are using the `Visitor pattern`_ +to parse all the nodes in the document. + +Let's focus on the ``PHPFileExtractor`` only for a moment. We are using the Nikic +PHP Parser to split the PHP source into an abstract syntax tree which enables us +to statically analyze the source. Read more about this in the `nikic/php-parser`_ +documentation. When you add a visitor to the ``PHPFileExtractor`` it will be called +for each node in the syntax tree. + +The visitors is very specific with what they are looking for. The ``FlashMessage`` +visitor is searching for a pattern like ``$this->addFlash()``. If that string is +found it will add a new ``SourceLocation`` to the ``SourceCollection`` model. + +When all visitors and ``FileExtractor`` has been executed an instance of the ``SourceCollection`` +will be returned. + +.. note:: + + 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. + + + +.. _`Visitor pattern`: https://en.wikipedia.org/wiki/Visitor_pattern +.. _`nikic/php-parser`: https://github.com/nikic/PHP-Parser + diff --git a/components/platform-adapters.rst b/components/platform-adapters.rst new file mode 100644 index 0000000..f19a46e --- /dev/null +++ b/components/platform-adapters.rst @@ -0,0 +1,48 @@ +Platform Adapters +================= + +To be able to integrate with all the third party translation platforms we need adapters +for each of them. The adapter converts the ``ThirdPartyPlatformApiClient`` into +a ``Translation\Common\Storage``. + +The `platform adapter repository`_ is a "monolithic" repository. It uses `www.subtreesplit.com`_ +to push changes from ``php-translation/platform-adapter`` to ``php-translation/foo-adapter``. +This setup will make it easier to maintain the adapters since it requires only one +pull request to make a change on many adapters. Note that ``php-translation/foo-adapter`` +is a **read only** repository and changes should go to ``php-translation/platform-adapter``. + +The Adapters +------------ + +Each adapter has a a dependency on a API client. They also have different Composer +requirements and may support different PHP version. All the adapters has a Symfony +bundle for ease the integration with Symfony. + +To install an adapter in Symfony you need to download it with Composer, activate +the bundle in ``AppKernel`` and then add some configuration. This procedure is described +at each adapters repository. + +.. note:: + + See guide :doc:`../guides/using-loco-adapter` + +The table below shows the adapters and their platform where you can read more about +the service. + + +.. csv-table:: + :header: "Platform", "Repository", "Badges" + + "`Loco/Localise.biz `_", "`php-translation/loco-adapter `_", |vLoco| |dLoco| + +.. _`platform adapter repository`: https://github.com/php-translation/platform-adapter +.. _`www.subtreesplit.com`: https://www.subtreesplit.com/ + +.. Badges: + +.. |vLoco| image:: https://poser.pugx.org/php-translation/loco-adapter/v/stable + :target: https://packagist.org/packages/php-translation/loco-adapter +.. |dLoco| image:: https://poser.pugx.org/php-translation/loco-adapter/downloads + :target: https://packagist.org/packages/php-translation/loco-adapter + + diff --git a/components/symfony-bundle.rst b/components/symfony-bundle.rst deleted file mode 100644 index c694ec3..0000000 --- a/components/symfony-bundle.rst +++ /dev/null @@ -1,59 +0,0 @@ -Symfony Translation Bundle -========================== - -Installation ------------- - -.. code-block:: bash - - composer require php-translation/symfony-bundle - - -.. code-block:: php - - new Translation\Bundle\TranslationBundle(), - - -WebUI ------ - -.. code-block:: yaml - - // config.yml - translation: - locales: ["sv", "en"] - webui: - enabled: true - configs: - app: - dirs: ["%kernel.root_dir%/Resources/views", "%kernel.root_dir%/../src"] - output_dir: "%kernel.root_dir%/Resources/translations" - excluded_names: ["*TestCase.php", "*Test.php"] - excluded_dirs: [cache, data, logs] - - -.. code-block:: yaml - - // routing_dev.yml - _translation_webui: - resource: "@TranslationBundle/Resources/config/routing_webui.yml" - prefix: /admin - -Go to http://localhost.dev/app_dev.php/admin/_trans - -Symfony Profiler Integration ----------------------------- - -.. code-block:: yaml - - // config.yml - translation: - locales: ["sv", "en"] - symfony_profiler: - enabled: true - -.. code-block:: yaml - - // routing_dev.yml - _translation_profiler: - resource: '@TranslationBundle/Resources/config/routing_symfony_profiler.yml' diff --git a/components/translator.rst b/components/translator.rst new file mode 100644 index 0000000..5addbb3 --- /dev/null +++ b/components/translator.rst @@ -0,0 +1,39 @@ +Translator +========== + +The Translator component provides an interface for translation services like Google +Translate or Bing Translate. + +Installation and Usage +---------------------- + +Install the extractor component with Composer + +.. code-block:: bash + + composer require php-translation/translator + +.. code-block:: php + + require "vendor/autoload.php"; + + $translator = new Translator(); + $translator->addTranslatorService(new GoogleTranslator('api_key')); + + echo $translator->translate('apple', 'en', 'sv'); // "äpple" + +Architecture +------------ + +The ``Translator`` class could be considered a "chain translator" it asks the first +translation service to translate the string. If the translation fails it asks the +second service until a translation is found. If no translation is found a ``null`` +value will be returned. + +The ``Translator`` class is SOLID so you can easily add your custom translator into +the chain. + +.. note:: + + Since most translator services are paid services you probably want to add aggressive + caching on the responses. See :doc:`../guides/configure-httplug` for more information. diff --git a/conf.py b/conf.py index 1a1962a..3bb6bc7 100644 --- a/conf.py +++ b/conf.py @@ -1,6 +1,6 @@ # -*- coding: utf-8 -*- # -# PHP-HTTP documentation build configuration file, created by +# PHP-Translation documentation build configuration file, created by # sphinx-quickstart on Sat Jan 2 15:26:57 2016. # # This file is execfile()d with the current directory set to its @@ -21,7 +21,7 @@ lexers['php'] = PhpLexer(startinline=True, linenos=1) lexers['php-annotations'] = PhpLexer(startinline=True) -primary_domain = 'php' +# primary_domain = 'php' highlight_language = 'php' # If extensions (or modules to document with autodoc) are in another directory, diff --git a/development/contributing.rst b/development/contributing.rst index 5399649..e18b36b 100644 --- a/development/contributing.rst +++ b/development/contributing.rst @@ -18,7 +18,7 @@ Security Issues --------------- If you discover any security related issues, -please contact us at security@php-http.org instead of submitting an issue on GitHub. +please contact us at tobias.nyholm@gmail.com instead of submitting an issue on GitHub. This allows us to fix the issue and release a security hotfix without publicly disclosing the vulnerability. diff --git a/favicon.ico b/favicon.ico new file mode 100644 index 0000000..3f98287 Binary files /dev/null and b/favicon.ico differ diff --git a/guides/adding-extractor.rst b/guides/adding-extractor.rst index 77a6c66..21598a7 100644 --- a/guides/adding-extractor.rst +++ b/guides/adding-extractor.rst @@ -2,14 +2,18 @@ Adding extractors ================= The extractor library is very SOLID which means that you easily can add extractors -without changing existing code. There are some concepts to be aware of: +without changing existing code. There are some concepts to be aware of -The ``Extrator`` object has a collection of **FileExtractor** that are executed +The ``Extractor`` object has a collection of ``FileExtractor`` that are executed on files with a file type they support. The ``PHPFileExtractor`` and ``TwigFileExtractor`` -are using the `visitor pattern`_. -They have a collection of ``Translation\Extractor\Visitor`` that will be executed -for each file the FileExtractor is running for. To add a custom extractor for a -custom PHP class you may only add a visitor for the ``PHPFileExtractor``. +are using the `visitor pattern`_. They have a collection of ``Translation\Extractor\Visitor`` +that will be executed for each file the FileExtractor is running for. To add a +custom extractor for a custom PHP class you may only add a visitor for the ``PHPFileExtractor``. + +.. note:: + + Read more about the architecture at the component description of + :doc:`../components/extractor`. Example ------- diff --git a/guides/configure-httplug.rst b/guides/configure-httplug.rst index 8e34247..6b8b13b 100644 --- a/guides/configure-httplug.rst +++ b/guides/configure-httplug.rst @@ -9,6 +9,6 @@ When you are using the auto translation features you may want to cache the respo from your paid third party translator services. To configure HTTPlug to be aggressive for those request you need the CachePlugin and the UrlMathcher. -TODO Show how to configure the CachePlugin to cache google translate calls. +TODO Show how to configure the CachePlugin to cache Google translate calls. .. _introduction: http://docs.php-http.org/en/latest/httplug/users.html diff --git a/guides/using-loco-adapter.rst b/guides/using-loco-adapter.rst new file mode 100644 index 0000000..eb2b370 --- /dev/null +++ b/guides/using-loco-adapter.rst @@ -0,0 +1,4 @@ +How to use Loco Adapter +======================= + +This is an example of how to use an platform adapter with the Symfony bundle. diff --git a/index.rst b/index.rst index db8ae88..f96e94c 100644 --- a/index.rst +++ b/index.rst @@ -21,18 +21,6 @@ This package include extractors that look at your source code and extract transl keys from it. We support extractor from PHP files, Twig files and Blade template files. -Platform adapters -````````````````` -.. image:: https://poser.pugx.org/php-translation/platform-adapter/v/stable - :target: https://packagist.org/packages/php-translation/platform-adapter - -.. image:: https://poser.pugx.org/php-translation/platform-adapter/downloads - :target: https://packagist.org/packages/php-translation/platform-adapter - :alt: Total Downloads - -The platform adapters integrate third party platforms like Localize.biz to a common -interface. - Common `````` .. image:: https://poser.pugx.org/php-translation/common/v/stable @@ -68,6 +56,14 @@ Symfony Bundle 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. + + .. toctree:: :hidden: @@ -79,20 +75,37 @@ for automatic translation, web UI, third party services and more. :caption: Guides Adding extractors + Configure Platform adapter Configure HTTPlug .. toctree:: :hidden: - :caption: Components + :caption: Best practice - Symfony bundle + Intro + Using service .. toctree:: :hidden: - :caption: Best practice + :caption: Symfony + + A bundle to rule them all + Configuration reference + Extracting translations + WebUI + Symfony Profiler UI + Edit in place + Auto translate + +.. toctree:: + :hidden: + :caption: Components + + Common + Extractor + Translator + Platform adapters - Intro - Using service .. toctree:: @@ -100,3 +113,4 @@ for automatic translation, web UI, third party services and more. :caption: --------- development/index.rst + diff --git a/spelling_word_list.txt b/spelling_word_list.txt index e7afab7..380085b 100644 --- a/spelling_word_list.txt +++ b/spelling_word_list.txt @@ -1,9 +1,18 @@ Backtrace +Bing Google hotfix +Nikic +organisation +Profiler +profiler +php rebase +runtime Semver sexualized +Storages sublicense Symfony wiki +workflow diff --git a/symfony/auto-translate.rst b/symfony/auto-translate.rst new file mode 100644 index 0000000..9e0eafe --- /dev/null +++ b/symfony/auto-translate.rst @@ -0,0 +1,43 @@ +Automatically Translate +======================= + +When your application is in production and you request for a translation that happens +to be missing, the default action is to check if the translation exists in the +*fallback locale*. If we are "lucky" we show a string in the fallback language. + +This could be done better. With the *auto translate* feature we can try to translate +the string in the fallback language to the requested language using a translation +service like Google Translate. + +Installation +------------ + +To use this feature you need to install *php-translation/translator*. + +.. code-block:: bash + + composer require php-translation/translator + +.. note:: + + If you are having issues installing. See :doc:`../guides/configure-httplug`, + +Configuration +------------- + +.. code-block:: yaml + + # config/config.yml + translation: + # .. + fallback_translation: + service: 'google' + api_key: 'foobar' + # .. + +Usage +----- + +That's it. You do not have to do anything more. It is however a good idea to add +some aggressive caching on the responses from the translation service in order to +remove the need of paying for the same translation twice. See how you :doc:`../guides/configure-httplug`. diff --git a/symfony/configuration-reference.rst b/symfony/configuration-reference.rst new file mode 100644 index 0000000..eee7a7c --- /dev/null +++ b/symfony/configuration-reference.rst @@ -0,0 +1,4 @@ +Configuration reference +======================= + +TODO diff --git a/symfony/edit-in-place.rst b/symfony/edit-in-place.rst new file mode 100644 index 0000000..f0e6cba --- /dev/null +++ b/symfony/edit-in-place.rst @@ -0,0 +1,4 @@ +Edit in Place +============= + +TODO https://github.com/php-translation/symfony-bundle/pull/23 diff --git a/symfony/extracting-translations.rst b/symfony/extracting-translations.rst new file mode 100644 index 0000000..4c427d1 --- /dev/null +++ b/symfony/extracting-translations.rst @@ -0,0 +1,4 @@ +Extracting Translations from Source +=================================== + +TODO example how to extract source. Show different configurations and commands. diff --git a/symfony/index.rst b/symfony/index.rst new file mode 100644 index 0000000..a3a29cb --- /dev/null +++ b/symfony/index.rst @@ -0,0 +1,96 @@ +Symfony Translation Bundle +========================== + +The Symfony bundle is filled with cool features that will ease your translation +workflow. You probably do not want **all features** enabled, just choose the ones +you like. Some features requires you to install extra packages, but that is explained +in the documentation for each feature. + +Features +-------- + +- :doc:`extracting-translations` +- :doc:`webui` +- :doc:`profiler-ui` +- :doc:`edit-in-place` +- :doc:`auto-translate` + +Installation +------------ + +Install the bundle with Composer + +.. code-block:: bash + + composer require php-translation/symfony-bundle + + +Then enable the bundle in AppKernel.php + +.. code-block:: php + + class AppKernel extends Kernel + { + public function registerBundles() + { + $bundles = array( + // ... + new Translation\Bundle\TranslationBundle(), + } + } + } + +Configuration +------------- + +The bundle has a very flexible configuration. It allows you do have different setups +for different parts of your application. This might be overkill for most applications +but it is possible by specifying more keys under ``translation.configs``. + +Below is an example of configuration that is great to start with. + +.. code-block:: yaml + + translation: + locales: ["en", "fr", "sv"] + configs: + app: + dirs: ["%kernel.root_dir%/Resources/views", "%kernel.root_dir%/../src"] + output_dir: "%kernel.root_dir%/Resources/translations" + excluded_names: ["*TestCase.php", "*Test.php"] + excluded_dirs: [cache, data, logs] + +With the configuration above you may extract all translation key from your source +code by running + +.. code-block:: bash + + php bin/console translation:extract app + +.. note:: + + See page :doc:`extracting-translations` for more information. + + +Storages +-------- + +By default we store all translations on the file system. This is highly configurable. +Many developers keep a local copy of all translations but do also use a remote storage, +like a translations platform. You may also create your own storage. A storage service +must implement `Translation\Common\Storage`. + +.. code-block:: yaml + + translation: + locales: ["en", "fr", "sv"] + configs: + app: + dirs: ["%kernel.root_dir%/Resources/views", "%kernel.root_dir%/../src"] + output_dir: "%kernel.root_dir%/Resources/translations" + remote_storage: ["php_translation.adapter.loco"] + 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>` +or see an example on how to :doc:`install an adapter <../guides/using-loco-adapter>`. diff --git a/symfony/profiler-ui.rst b/symfony/profiler-ui.rst new file mode 100644 index 0000000..c095c43 --- /dev/null +++ b/symfony/profiler-ui.rst @@ -0,0 +1,28 @@ +Symfony Profiler UI +=================== + +The Symfony profiler page for translation is great. You see all translations that +were used in that request. But what if you could edit those translations as well? +This is exactly what this feature does. It is way easier to edit and add new translations +since the *missing translations* are highlighted. + + +Configuration +------------- + +.. code-block:: yaml + + # config/config.yml + translation: + # .. + symfony_profiler: + enabled: true + +.. code-block:: yaml + + # config/routing_dev.yml + _translation_profiler: + resource: '@TranslationBundle/Resources/config/routing_symfony_profiler.yml' + +See the updated Translation page in the Symfony profiler. There are some new buttons +on the right hand side. diff --git a/symfony/webui.rst b/symfony/webui.rst new file mode 100644 index 0000000..b674f54 --- /dev/null +++ b/symfony/webui.rst @@ -0,0 +1,41 @@ +Symfony WebUI +============= + +The Symfony WebUI feature bring you a web interface to add, edit and remove translations. + +.. image:: /assets/image/webui-dashboard.png + :width: 300px + :align: left + +.. image:: /assets/image/webui-page.png + :width: 300px + :align: left + +|clearfloat| + +Configuration +------------- + +.. code-block:: yaml + + # config/config.yml + translation: + # .. + webui: + enabled: true + # .. + + +.. code-block:: yaml + + # config/routing_dev.yml + _translation_webui: + resource: "@TranslationBundle/Resources/config/routing_webui.yml" + prefix: /admin + +Go to http://localhost.dev/app_dev.php/admin/_trans + + +.. |clearfloat| raw:: html + +