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

composer require charcoal/translator

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

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

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) {
    // ...
}

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

Charcoal\Translator\LocalesManager

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

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"
    }
}

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.

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

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"
            }
        }
    }
}

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.

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

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