Charcoal service provider for translating messages and managing locales. 2020-03-09 17:20 UTC


License Latest Stable Version Code Quality Coverage Status SensioLabs Insight Build Status

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


  1. The preferred (and only supported) method is with Composer:

    ★ composer require locomotivemtl/charcoal-translator
  2. 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.




  • PSR-7: Common interface for HTTP messages. Followed by LanguageMiddleware.
  • PSR-11: Common interface for dependency containers. Fulfilled by Pimple.



The Translation Object


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'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


The Locales Manager is used to manage available locales / languages and keep track of current language.

The Parser Script


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.


  • 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.



Here is an example of configuration:

"locales": {
    "languages": {
        "de": {},
        "en": {},
        "es": {
            "active": false
        "fr": {}
    "default_language": "fr",
    "fallback_languages": [
    "auto_detect": true
"translator": {
    "loaders": [
    "paths": [
    "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"


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.

Setting Type Default Description
active boolean FALSE Whether to enable or disable the middleware (locomotivemtl/charcoal-app only).
default_language string null The default language to use if no other languages is choosen.
browser_language string null The client's preferred language (Accept-Language).
use_browser boolean true Whether to use browser_language as the default language.
use_path boolean true Whether to lookup the HTTP request's URI path for a language code.
excluded_path `string array` ^/admin\b
path_regexp `string array` ^/([a-z]{2})\b
use_params boolean false Whether to lookup the HTTP request's URI query string for a language code.
param_key `string array` current_language
use_session boolean true Whether to lookup the client's PHP session for a preferred language.
session_key `string array` current_language
use_host boolean false Whether to lookup the server host for a language code.
host_map `string array` []
set_locale boolean true Whether to set the environment's locale.




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.)


To install the development environment:

★ composer install --prefer-source

To run the scripts (phplint, phpcs and phpunit):

★ composer tests

API Documentation

Development Dependencies

Coding Style

The charcoal-translator module follows the Charcoal coding-style:

Coding style validation / enforcement can be performed with composer phpcs. An auto-fixer is also available with composer phpcbf.



Charcoal is licensed under the MIT license. See LICENSE for details.