Charcoal Translator

The Transator package provides tools to internationalize Web applications with support for multilingual data and an integration with Symfony's Translation component.

Installation

composer require charcoal/translator

For Charcoal projects, the service provider can be registered from your configuration file:

{
    "service_providers": {
        "charcoal/translator/service-provider/translator": {}
    }
}

Overview

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/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 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:

use Charcoal\Translator\Middleware\LanguageMiddleware;
use Slim\App;

$app = new App();

// Register middleware
$app->add(new 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 (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.

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

Resources

• Contributing
• Report issues and send pull requests in the main Charcoal repository