Developed with love by KnpLabs Hire us for your project!
68

KunstmaanTranslatorBundle

by Kunstmaan

[READ-ONLY] Subtree split of the Kunstmaan TranslatorBundle -- master at Kunstmaan/KunstmaanBundlesCMS

KunstmaanTranslatorBundle

Build Status
Total Downloads
Latest Stable Version
Analytics

A bundle which enables editing translations in the admin interface without need for editing the translations files.
Translations will be stored in a (default) database and retrieved on the most efficient way possible.

Symfony Profiler Example

Installation requirements

You should be able to get Symfony >=2.3 up and running before you can install the KunstmaanTranslatorBundle.

Installation instructions

Assuming you have installed composer.phar or composer binary:

$ composer require kunstmaan/translator-bundle 2.3.*@dev
$ composer require doctrine/migrations dev-master
$ composer require doctrine/doctrine-migrations-bundle dev-master

Add the KunstmaanTranslatorBundle to your AppKernel.php file:

new Kunstmaan\TranslatorBundle\KunstmaanTranslatorBundle(),
new Doctrine\Bundle\MigrationsBundle\DoctrineMigrationsBundle(),

Add the KunstmaanTranslatorBundle to your routing.yml. Take your own routing into account, it's possible you will need to add the following code prior to your own routing configurations

KunstmaanTranslatorBundle:
    resource: "@KunstmaanTranslatorBundle/Resources/config/routing.yml"
    prefix:   /{_locale}/
    requirements:
        _locale: "%requiredlocales%"

Configuration

Overwrite the KunstmaanTranslatorBundle config to your needs in config.yml, these are the default values:

kunstmaan_translator:
    enabled:         true
    default_bundle:  own
    bundles:         []
    cache_dir:       %kernel.cache_dir%/translations
    managed_locales: []
    file_formats:    ['yml', 'yaml', 'xliff']
    debug:           defaults to the kernel.debug parameter (boolean)
  • enabled : Enabled or disable the KunstmaanTranslatorBundle
  • default_bundle : Which bundles are used for the import functionality in the backend. Possible values: 'own', 'all', 'custom'.
    • own : All bundles in your src directory
    • all : All bundles in your src directory + all bundles in your vendor directory
    • custom : Only the bundles you specify in bundles
  • bundles : A list of bundles that will be used for the import functionality in the backend. Only used when default_bundle is set to 'custom'.
  • cache_dir : Cached translations dir
  • managed_locales : Which locale translation files should be imported
  • file_formats : Which type of translation files should be imported
  • debug : When debug is enabled the translation caching is disabled

Example configurations:

kunstmaan_translator:
    managed_locales: ['en', 'fr', 'es']
kunstmaan_translator:
    default_bundle: own
    managed_locales: ['en', 'fr', 'es']
    debug: false
kunstmaan_translator:
    enabled: true
    default_bundle: custom
    bundles: ['MyCompanyCoolBundle', 'MyCompanyAwesomeBundle']
    managed_locales: ['en', 'fr', 'es']

Database schema

Update your database schema with doctrine

bin/console doctrine:schema:update --force

Database schema updated successfully! "1" queries were executed

Migrate dev translations to production

Use the following command to generate a doctrine migration with all new and updated translations from your current environment.

bin/console kuma:translator:migrations:diff

When you want to include these migrated translations into your (other) environment use the normal doctrine migrate command.

bin/console doctrine:migrations:migrate

Import existing translation files

When migrating your current project you can easily import the existing translation files.

Without parameters, all translations, locales from the current main project will be included.
If you have already existing translations in the database with the same combination of 'domain', 'keyword', 'locale', non of them will be overwritten

bin/console kuma:translator:import

To force overwrite the existing translations in the stasher:

bin/console kuma:translator:import --force

To import translations from a specific bundle:

bin/console kuma:translator:import --bundle=superCoolNewApplicationBundle

To import only specific locales:

bin/console kuma:translator:import --locales=nl,fr,de

To import translations from the global Resources (app/Resources/translations)

bin/console kuma:translator:import --globals

How does the cache work

Translations are stored in a database, but cached (as Symfony normally does) when not running in debug mode.

$kernel = new AppKernel('prod', false); // translations are cached an read from this cache
$kernel = new AppKernel('dev', true); // translations are always loaded from the stash (slower, more queries)

When editing translations in the backend changes aren't immediately visible on your website.
The backend will show a warning message when not newer or updated translations aren't loaded into the cache.
Click on the Refresh live button to rebuild the cache.

Clear cache and request status

Clear translation cache files, this will trigger a rebuild of the translation cache when visiting a page

bin/console kuma:translator:cache --flush

Request status of the current cache

bin/console kuma:translator:cache --status

Reset translation flags

When all translations are up to date, e.g when migrated all develop translations into production. You need to reset all the flags which mark translations as new or updated.
Otherwise already migrated translations will be added into later migrations again (which can cause errors with inserts and unique keys)

bin/console kuma:translator:flag --reset

Lookup keyword/domain of your translations

You probably don't always remember which keyword and/or domain your translations on specific pages are using. To solve this problem you can add an extra GET parameter to your request. Add ?transSource=1 to your url to see all sources of the translated labels.

You instead of "Hello world" you might see header.hello_world (messages). This means:

  • keyword is header.hello_world
  • domain is messages

Symfony Profiler integration

The Symfony Profiler show the number of translations used on the current request:

Symfony Profiler Example

When you click on this item, you can see all translations used on the current request and a link to add or edit them in the Kunstmaan Admin backend.

Symfony Profiler Example Table

Workflow example (new project)

  1. Add translations (with keywords) in your template files (dev)
  2. Add the translations of (1) into your backend via "Add Translation" (dev)
  3. Repeat 1 & 2
  4. Create migrations diff bin/console kuma:translator:migrations:diff (dev)
  5. Reset translation flags bin/console kuma:translator:flag --reset (dev)
  6. Deploy your application
  7. Execute doctrine migrations bin/console doctrine:migrations:migrate (prod)
  8. Edit/add translations (prod)
  9. When ready editing/adding, click Refresh live or bin/console kuma:translator:cache --flush (prod)
  10. Repeat 7 & 8 when editing/adding translations in prod

Workflow example (existing project)

  1. Import current translations, click Import -> Import or bin/console kuma:translator:import (prod/dev)
  2. If you did 1 in dev, go to 4 of "Workflow example (new project)", otherwise go to 7 "Workflow example (new project)"

Features

  • Import bundle/global translations from any type of translation file
  • Import only specific translations (onlu from console command)
  • Force import to overwrite existing translations with same domain/keyword/locale
  • Edit stored translations from the backend interface
  • Add new translations from the backend interface
  • Translations are cached (if debug is disabled)
  • Warning when cached translations aren't up to date with the stored translations
  • Clear translation cache to rebuild translations from the stored translations
  • Newer or updated translations are flagged
  • Create a Doctrine Migrations file with all flagged translations
  • Reset all flagged translations (from console command)
  • Clear and check translation cache from console command
  • Check your page with the keyword and domain of all translations

Development instructions

Run unit tests

./vendor/bin/phpunit -c phpunit.xml.dist

Run PHP CS Fixer, after installing php-cs-fixer system wide

php-cs-fixer fix .

How to create your own file exporter

  • Tag your exporter with `translation.exporter
  • implement \Kunstmaan\TranslatorBundle\Service\Exporter\FileExporterInterface

NOTE : exporting isn't stable (yet)

The MIT License

Copyright (c) 2013 Kunstmaan (http://www.kunstmaan.be)

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
kuma_translator:
enabled: true
default_bundle: own
bundles: []
cache_dir: %kernel.cache_dir%/translations
debug: ~
managed_locales: []
file_formats:

# Defaults:
- yml
- yaml
- xliff
storage_engine:
type: orm
  • Merge pull request #2662 from acrobat/replace-doctrine-entity-alias
    By web-flow, 3 months ago
  • [AllBundles] Fix phpstan level 1 issues
    By acrobat, 5 months ago
  • [AllBundles] Replace deprecated string entity alias to fqcn
    By acrobat, 6 months ago
  • Update composer branch aliases
    By acrobat, 7 months ago
  • [AllBundles] Adding .gitattributes to remove Tests directory from "dist" packages
    By acrobat, 7 months ago
  • Apply fixes from StyleCI
    By StyleCIBot, 9 months ago
  • Merge pull request #2603 from Numkil/feature/useCommonExportLogicInsteadOfCustomExportForTranslations
    By web-flow, 9 months ago
  • [TranslatorBundle] use the common export logic instead of a custom export
    By Numkil, 9 months ago
  • [AllBundles] Commands should return an integer exitcode
    By acrobat, 10 months ago
  • Merge pull request #2545 from acrobat/fix-self-deprecations-triggered-in-tests
    By web-flow, 10 months ago
  • [AllBundles] Switch to twig namespaced path notation
    By acrobat, 10 months ago
  • Merge branch '5.3'
    By acrobat, 10 months ago
  • [AllBundles] Fix symfony 4.4 test failures
    By acrobat, 10 months ago
  • [TranslatorBundle] implement changeablelimitinterface on translationadminlist
    By Numkil, 11 months ago
  • Merge pull request #2472 from acrobat/translator-bundle-code-improvements
    By web-flow, 11 months ago
  • [TranslatorBundle] Code improvement found by static code analysis
    By acrobat, 11 months ago
  • Merge branch '5.3'
    By acrobat, 1 year ago
  • [TranslatorBundle] Fix import translations on symfony 3.4 installations
    By acrobat, 1 year ago
  • Merge branch '5.3'
    By acrobat, 1 year ago
  • [TranslatorBundle] Tweak test app config to resolve some indirect deprecations
    By acrobat, 1 year ago
  • [TranslatorBundle] Tag translator to inject correct locale on sf4.3
    By acrobat, 1 year ago
  • Merge branch '5.3'
    By acrobat, 1 year ago
  • [TranslatorBundle] Restored missing service alias for translator datacollector (#2502)
    By Devolicious, 1 year ago
  • [TranslatorBundle] Remove useless loop that doesn't loop (#2474)
    By Devolicious, 1 year ago
  • [AllBundles] Improve the kunstmaan toolbar items (#2477)
    By Devolicious, 1 year ago
  • [AllBundle] Code style fixes (#2450)
    By Devolicious, 1 year ago
  • [AdminListBundle] [TranslatorBundle] Option to filter on empty fields in StringFilterType. (#2434)
    By Devolicious, 1 year ago
  • [AllBundle] Separate bundle phpunit config and cleanup old files (#2419)
    By Devolicious, 1 year ago
  • [AllBundles] Replace deprecated getRootDir calls (#2421)
    By Devolicious, 1 year ago
  • Merge branch '5.2'
    By Devolicious, 1 year ago