kunstmaan / translator-bundle
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.
Installs: 116 188
Dependents: 3
Suggesters: 1
Security: 0
Stars: 50
Watchers: 16
Forks: 10
Type:symfony-bundle
Requires
- php: ^8.1
- kunstmaan/adminlist-bundle: ^7.0
- openspout/openspout: ^4.0
Requires (Dev)
- doctrine/data-fixtures: ^1.5
- fakerphp/faker: ^1.15
- matthiasnoback/symfony-config-test: ^4.2.1
- matthiasnoback/symfony-dependency-injection-test: ^4.2.1
- phpunit/phpunit: ^9.5.5
- symfony/phpunit-bridge: ^7.0
- 7.x-dev
- 7.1.x-dev
- 7.1.2
- 7.1.1
- 7.1.0
- 7.1.0-alpha2
- 7.1.0-alpha1
- 7.0.x-dev
- 7.0.5
- 7.0.4
- 7.0.3
- 7.0.2
- 7.0.1
- 7.0.0
- 7.0.0-alpha1
- 6.x-dev
- 6.4.x-dev
- 6.4.3
- 6.4.2
- 6.4.1
- 6.4.0
- 6.4.0-alpha2
- 6.4.0-alpha1
- 6.3.x-dev
- 6.3.1
- 6.3.0
- 6.2.x-dev
- 6.2.5
- 6.2.4
- 6.2.3
- 6.2.2
- 6.2.1
- 6.2.0
- 6.1.x-dev
- 6.1.9
- 6.1.8
- 6.1.7
- 6.1.6
- 6.1.5
- 6.1.4
- 6.1.3
- 6.1.2
- 6.1.1
- 6.1.0
- 6.0.x-dev
- 6.0.6
- 6.0.5
- 6.0.4
- 6.0.3
- 6.0.2
- 6.0.1
- 6.0.0
- 5.10.x-dev
- dev-master / 5.10.x-dev
- 5.10.7
- 5.10.6
- 5.10.5
- 5.10.4
- 5.10.3
- 5.10.2
- 5.10.1
- 5.10.0
- 5.9.x-dev
- 5.9.3
- 5.9.2
- 5.9.1
- 5.9.0
- 5.8.x-dev
- 5.8.1
- 5.8.0
- 5.7.x-dev
- 5.7.3
- 5.7.2
- 5.7.1
- 5.7.0
- 5.6.x-dev
- 5.6.6
- 5.6.5
- 5.6.4
- 5.6.3
- 5.6.2
- 5.6.1
- 5.6.0
- 5.5.x-dev
- 5.5.6
- 5.5.5
- 5.5.4
- 5.5.3
- 5.5.2
- 5.5.1
- 5.5.0
- 5.4.x-dev
- 5.4.7
- 5.4.6
- 5.4.5
- 5.4.4
- 5.4.3
- 5.4.2
- 5.4.1
- 5.4.0
- 5.3.x-dev
- 5.3.14
- 5.3.13
- 5.3.12
- 5.3.11
- 5.3.10
- 5.3.9
- 5.3.8
- 5.3.7
- 5.3.6
- 5.3.5
- 5.3.4
- 5.3.3
- 5.3.2
- 5.3.1
- 5.3.0
- 5.2.x-dev
- 5.2.5
- 5.2.4
- 5.2.3
- 5.2.2
- 5.2.1
- 5.2.0
- 5.1.x-dev
- 5.1.2
- 5.1.1
- 5.1.0
- 5.0.x-dev
- 5.0.14
- 5.0.13
- 5.0.12
- 5.0.11
- 5.0.10
- 5.0.9
- 5.0.8
- 5.0.7
- 5.0.6
- 5.0.5
- 5.0.4
- 5.0.3
- 5.0.2
- 5.0.1
- 5.0.0
- 5.0.0-RC2
- 5.0.0-RC1
- 4.2.x-dev
- 4.2.3
- 4.2.2
- 4.2.1
- 4.2.0
- 4.1.x-dev
- 4.1.4
- 4.1.3
- 4.1.2
- 4.1.1
- 4.1.0
- 4.0.x-dev
- 4.0.3
- 4.0.2
- 4.0.1
- 4.0.0
- 4.0.0-RC1
- 3.6.x-dev
- 3.6.3
- 3.6.2
- 3.6.1
- 3.6.0
- 3.5.x-dev
- 3.5.2
- 3.5.1
- 3.5.0
- 3.4.x-dev
- 3.4.2
- 3.4.1
- 3.4.0
- 3.3.x-dev
- 3.3.4
- 3.3.3
- 3.3.2
- 3.3.1
- 3.3.0
- 3.2.x-dev
- 3.2.6
- 3.2.5
- 3.2.4.1
- 3.2.4
- 3.2.3
- 3.2.2
- 3.2.1.1
- 3.2.1
- 3.2.0
- 3.1.x-dev
- 3.1.4
- 3.1.3
- 3.1.2
- 3.1.1
- 3.1.0
- 3.0.x-dev
- 3.0.3
- 3.0.2
- 3.0.1
- 3.0.0
- v2.3.15
- v2.3.14
- v2.3.13
- v2.3.12
- v2.3.11
- v2.3.10
- v2.3.9
- v2.3.8
- v2.3.7
- v2.3.6
- v2.3.5
- v2.3.4
- v2.3.3
- v2.3.2
- v2.3.1
- v2.3.0
- dev-6.0-copy
- dev-sf3
This package is auto-updated.
Last update: 2024-11-01 22:22:19 UTC
README
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.
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 KunstmaanTranslatorBundledefault_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 whendefault_bundle
is set to 'custom'.cache_dir
: Cached translations dirmanaged_locales
: Which locale translation files should be importedfile_formats
: Which type of translation files should be importeddebug
: 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:
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.
Workflow example (new project)
- Add translations (with keywords) in your template files (dev)
- Add the translations of (1) into your backend via "Add Translation" (dev)
- Repeat 1 & 2
- Create migrations diff
bin/console kuma:translator:migrations:diff
(dev) - Reset translation flags
bin/console kuma:translator:flag --reset
(dev) - Deploy your application
- Execute doctrine migrations
bin/console doctrine:migrations:migrate
(prod) - Edit/add translations (prod)
- When ready editing/adding, click
Refresh live
orbin/console kuma:translator:cache --flush
(prod) - Repeat 7 & 8 when editing/adding translations in prod
Workflow example (existing project)
- Import current translations, click
Import -> Import
orbin/console kuma:translator:import
(prod/dev) - 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)