locomotivemtl / charcoal-translator
Charcoal service provider for translating messages and managing locales.
Installs: 17 748
Dependents: 11
Suggesters: 0
Security: 0
Stars: 0
Watchers: 15
Forks: 0
Open Issues: 1
Requires
- php: >=5.6.0 || >=7.0
- locomotivemtl/charcoal-config: ~0.8
- pimple/pimple: ^3.0
- symfony/translation: ^3.4
Requires (Dev)
- locomotivemtl/charcoal-admin: ~0.8
- mockery/mockery: ^0.9
- php-coveralls/php-coveralls: ^2.0
- phpunit/phpunit: ^5.7 || ^6.5
- squizlabs/php_codesniffer: ^3.0
Suggests
- locomotivemtl/charcoal-app: To run the parser script.
This package is auto-updated.
Last update: 2024-10-12 01:05:31 UTC
README
A Charcoal service provider for the Symfony Translation component.
Provides internationalization (I18N) tools for translating messages and managing locales in multilingual applications.
Table of Contents
Installation
-
The preferred (and only supported) method is with Composer:
★ composer require locomotivemtl/charcoal-translator
-
Add the service provider and configure the default translator / locale services via the application configset:
"service_providers": { "charcoal/translator/service-provider/translator": {} }, "translator": { // … }, "locales": { // … }
or via the service container:
$container->register(new \Charcoal\Translator\ServiceProvider\TranslatorServiceProvider()); $container['translator/config'] = new \Charcoal\Translator\TranslatorConfig([ // … ]); $container['locales/config'] = new \Charcoal\Translator\LocalesConfig([ // … ]);
If you are using locomotivemtl/charcoal-app, the [TranslatorServiceProvider
][translator-provider] is automatically registered by the AppServiceProvider
.
Dependencies
Required
- PHP 5.6+: PHP 7 is recommended.
- symfony/translation: Translation component which Charcoal's translator service extends.
- pimple/pimple: PSR-11 compliant service container and provider library.
- locomotivemtl/charcoal-config: For configuring the translator service and locales.
PSR
- PSR-7: Common interface for HTTP messages. Followed by
LanguageMiddleware
. - PSR-11: Common interface for dependency containers. Fulfilled by Pimple.
Dependents
- locomotivemtl/charcoal-admin: Admin interface for Charcoal applications.
- locomotivemtl/charcoal-app: PSR-7 compliant framework for web applications.
For resolving the current locale via theLanguageMiddleware
. - locomotivemtl/charcoal-cms: Pre-designed models and basic utilities for content management (pages, news, events).
For supporting multilingual model properties and localizing model descriptors. - locomotivemtl/charcoal-property: Model property values and metadata.
For supporting multilingual values and localizing property descriptors.
Features
The Translation Object
Charcoal\Translator\Translation
The Translation Object holds the translation data for a given string in all available languages / locales.
// Get a translation object from the Translator $translation = $container['translator']->translation([ 'en' => 'Hello World', 'fr' => 'Bonjour' ]); // If cast to string, the default language will be used. echo $translation; // Use ArrayAccess to get (or set) a translated value. echo $translation['fr']; $translation['fr'] => 'Bonjour le monde'; // To loop through all translations: foreach ($translation->data() as $lang => $translatedValue) { // ... }
The Translator Service
Charcoal\Translator\Translator
Charcoal's Translator extends Symfony's Translator
to also provide two new translation methods (translation($val)
and translator($val)
) which can both accept mixed arguments to return either a Translation object, in the case of translation()
or a string, in the case of translate($val)
.
The Locales Manager
Charcoal\Translator\LocalesManager
The Locales Manager is used to manage available locales / languages and keep track of current language.
The Parser Script
Charcoal\Translator\Script\TranslationParserScript
The Parser Script is used to scrape files that contain translatable content. Add the following route to your application configuration:
"scripts": { "charcoal/translator/parse": { "ident": "charcoal/translator/script/translation-parser" } }
Service Provider
The TranslatorServiceProvider
provides services and options for translating your application into different languages.
Parameters
- locales/config: Configuration object for defining the available languages, fallbacks, and defaults.
- locales/default-language: Default language of the application, optionally the navigator's preferred language.
- locales/browser-language: Accepted language from the navigator.
- locales/fallback-languages: List of fallback language codes for the translator.
- locales/available-languages: List of language codes from the available locales.
- locales/languages: List of available language structures of the application.
- translator/config: Configuration object for translation service, message catalogs, and catalog loaders.
- translator/translations: Dictionary of additional translations grouped by domain and locale.
Services
- locales/manager: An instance of
LocalesManager
, used for handling available languages, their definitions, the default language, and tracks the current language. - translator: An instance of
Translator
, that is used for translation. - translator/message-selector: An instance of
Symfony\Component\Translation\MessageSelector
. - translator/loader/*: Instances of the translation
Symfony\Component\Translation\Loader\LoaderInterface
.
Configuration
Here is an example of configuration:
"locales": { "languages": { "de": {}, "en": {}, "es": { "active": false }, "fr": {} }, "default_language": "fr", "fallback_languages": [ "en", "fr" ], "auto_detect": true }, "translator": { "loaders": [ "xliff", "json", "php" ], "paths": [ "translations/", "vendor/locomotivemtl/charcoal-app/translations/" ], "debug": false, "cache_dir": "cache/translation/", "translations": { "messages": { "de": { "hello": "Hallo {{ name }}", "goodbye": "Auf Wiedersehen!" }, "en": { "hello": "Hello {{ name }}", "goodbye": "Goodbye!" }, "es": { "hello": "Hallo {{ name }}", "goodbye": "Adios!" }, "fr": { "hello": "Bonjour {{ name }}", "goodbye": "Au revoir!" } }, "admin": { "fr": { "Save": "Enregistrer" } } } }
Middleware
The LanguageMiddleware
is available for PSR-7 applications that support middleware. The middleware detects the preferred language using the Accept-Language
HTTP header, the URI path, query string, or host.
If you are using locomotivemtl/charcoal-app, you can add the middleware via the application configset:
"middlewares": { "charcoal/translator/middleware/language": { "active": true, "use_params": true, "param_key": "hl" } }
Otherwise, with Slim, for example:
$app = new \Slim\App(); // Register middleware $app->add(new \Charcoal\Translator\Middleware\LanguageMiddleware([ 'default_language' => 'fr', 'use_params' => true, 'param_key' => 'hl', ]));
The middleware comes with a set of default options which can be individually overridden.
Helpers
TranslatorAwareTrait
Charcoal\Translator\TranslatorAwareTrait
The TranslatorAwareTrait
is offered as convenience to avoid duplicate / boilerplate code. It simply sets and gets a Translator
service property.
Set with setTranslator()
and get with translator()
. Both are protected method. (This trait has no public interface.)
Development
To install the development environment:
★ composer install --prefer-source
To run the scripts (phplint, phpcs and phpunit):
★ composer tests
API Documentation
- The auto-generated
phpDocumentor
API documentation is available at:
https://locomotivemtl.github.io/charcoal-translator/docs/master/ - The auto-generated
apigen
API documentation is available at:
https://codedoc.pub/locomotivemtl/charcoal-translator/master/
Development Dependencies
Coding Style
The charcoal-translator module follows the Charcoal coding-style:
- PSR-1
- PSR-2
- PSR-4, autoloading is therefore provided by Composer.
- phpDocumentor comments.
- phpcs.xml.dist and .editorconfig for coding standards.
Coding style validation / enforcement can be performed with
composer phpcs
. An auto-fixer is also available withcomposer phpcbf
.
Credits
License
Charcoal is licensed under the MIT license. See LICENSE for details.