locomotivemtl/charcoal-translator

Charcoal service provider for translating messages and managing locales.

Tuesday, June 5, 2018
by mducharme
Repository
10 Watchers
0 Stars
8,205 Installations

PHP
9 Dependents
0 Suggesters
0 Forks
0 Open issues
24 Versions
13 % Grown

The README.md

Charcoal Translator

![License][badge-license] ![Code Quality][badge-scrutinizer] ![SensioLabs Insight][badge-sensiolabs] , _(*1)

A Charcoal service provider for the Symfony Translation component., _(*2)

Provides internationalization (I18N) tools for translating messages and managing locales in multilingual applications., _(*3)

Installation
- Dependencies
Features
Service Provider
- Parameters
- Services
Configuration
Middleware
Helpers
- TranslatorAwareTrait
Development
Credits
License

Installation

The preferred (and only supported) method is with Composer:, _(*4)
```
★ composer require locomotivemtl/charcoal-translator
```

Add the service provider and configure the default translator / locale services via the application configset:, _(*5)

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

"translator": {
    // …
},

"locales": {
    // …
}

or via the service container:, _(*6)

$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., _(*7)

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 the LanguageMiddleware.
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, _(*8)

The Translation Object holds the translation data for a given string in all available languages / locales., _(*9)

// 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, _(*10)

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)., _(*11)

The Locales Manager

Charcoal\Translator\LocalesManager, _(*12)

The Locales Manager is used to manage available locales / languages and keep track of current language., _(*13)

The Parser Script

Charcoal\Translator\Script\TranslationParserScript, _(*14)

The Parser Script is used to scrape files that contain translatable content. Add the following route to your application configuration:, _(*15)

"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., _(*16)

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:, _(*17)

"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., _(*18)

If you are using locomotivemtl/charcoal-app, you can add the middleware via the application configset:, _(*19)

"middlewares": {
    "charcoal/translator/middleware/language": {
        "active": true,
        "use_params": true,
        "param_key": "hl"
    }
}

Otherwise, with Slim, for example:, _(*20)

$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., _(*21)

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` \| One or more RegEx patterns to ignore from localization, when matching the URI path.
path_regexp	`string	array`	`^/([a-z]{2})\b` \| One or more RegEx patterns to include from localization, when matching the URI path.
use_params	`boolean`	`false`	Whether to lookup the HTTP request's URI query string for a language code.
param_key	`string	array`	`current_language` \| One or more RegEx patterns to include from localization, when matching the query string keys.
use_session	`boolean`	`true`	Whether to lookup the client's PHP session for a preferred language.
session_key	`string	array`	`current_language` \| One or more RegEx patterns to include from localization, when matching the session keys.
use_host	`boolean`	`false`	Whether to lookup the server host for a language code.
host_map	`string	array`	`[]` \| One or more RegEx patterns to include from localization, when matching the host.
set_locale	`boolean`	`true`	Whether to set the environment's locale.

Helpers

TranslatorAwareTrait

Charcoal\Translator\TranslatorAwareTrait, _(*22)

The TranslatorAwareTrait is offered as convenience to avoid duplicate / boilerplate code. It simply sets and gets a Translator service property., _(*23)

Set with setTranslator() and get with translator(). Both are protected method. (This trait has no public interface.), _(*24)

Development

To install the development environment:, _(*25)

★ composer install --prefer-source

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

★ 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:, _(*27)

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 with composer phpcbf., _(*28)

Credits

License

Charcoal is licensed under the MIT license. See LICENSE for details., _(*29)

The Versions

05/06 2018

dev-master

9999999-dev https://locomotivemtl.github.io/charcoal-translator/

Charcoal service provider for translating messages and managing locales.

library charcoal-translator

Charcoal service provider for translating messages and managing locales.

locomotivemtl/charcoal-translator

The README.md

Charcoal Translator

Table of Contents

Installation

Dependencies

Required

PSR

Dependents

Features

The Translation Object

The Translator Service

The Locales Manager

The Parser Script

Service Provider

Parameters

Services

Configuration

Middleware

Helpers

TranslatorAwareTrait

Development

API Documentation

Development Dependencies

Coding Style

Credits

License

The Versions

dev-master

The Requires

The Development Requires

by Mathieu Ducharme

by Locomotive

dev-mcaskill-patch-scripts

The Requires

The Development Requires

by Mathieu Ducharme

by Locomotive

0.3.5

The Requires

The Development Requires

by Mathieu Ducharme

by Locomotive

dev-mcaskill-patch-exists

The Requires

The Development Requires

by Mathieu Ducharme

by Locomotive

0.3.4

The Requires

The Development Requires

by Mathieu Ducharme

by Locomotive

0.3.3

The Requires

The Development Requires

by Mathieu Ducharme

by Locomotive

0.3.2

The Requires

The Development Requires

by Mathieu Ducharme

dev-mcaskill-patch-5

The Requires

The Development Requires

by Mathieu Ducharme

dev-mcaskill-patch-4

The Requires

The Development Requires

by Mathieu Ducharme

0.3.1

The Requires

The Development Requires

by Mathieu Ducharme

0.3

The Requires

The Development Requires

by Mathieu Ducharme