{"id":19250249,"url":"https://github.com/charcoalphp/translator","last_synced_at":"2026-06-10T21:31:30.726Z","repository":{"id":37491602,"uuid":"505906635","full_name":"charcoalphp/translator","owner":"charcoalphp","description":"[READ-ONLY] Charcoal Translator, based on Symfony's.","archived":false,"fork":false,"pushed_at":"2024-03-13T15:05:20.000Z","size":170,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-09-17T13:08:05.378Z","etag":null,"topics":["charcoal","i18n","intl","l10n","read-only-repository","translation","translator"],"latest_commit_sha":null,"homepage":"https://github.com/charcoalphp/charcoal","language":"PHP","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/charcoalphp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-06-21T15:45:18.000Z","updated_at":"2022-06-21T16:27:31.000Z","dependencies_parsed_at":"2024-01-13T04:49:47.818Z","dependency_job_id":"1fd912b0-5bd6-424b-8744-11490a33ed0e","html_url":"https://github.com/charcoalphp/translator","commit_stats":{"total_commits":95,"total_committers":9,"mean_commits":"10.555555555555555","dds":0.4842105263157894,"last_synced_commit":"ce4456b60724e740bd2f0dbba71d275364046c0c"},"previous_names":[],"tags_count":46,"template":false,"template_full_name":null,"purl":"pkg:github/charcoalphp/translator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charcoalphp%2Ftranslator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charcoalphp%2Ftranslator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charcoalphp%2Ftranslator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charcoalphp%2Ftranslator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/charcoalphp","download_url":"https://codeload.github.com/charcoalphp/translator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charcoalphp%2Ftranslator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34172196,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-10T02:00:07.152Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["charcoal","i18n","intl","l10n","read-only-repository","translation","translator"],"created_at":"2024-11-09T18:16:37.283Z","updated_at":"2026-06-10T21:31:30.703Z","avatar_url":"https://github.com/charcoalphp.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"Charcoal Translator\n===================\n\nThe Transator package provides tools to internationalize Web applications with support for multilingual data and an integration with [Symfony's Translation component](https://github.com/symfony/translation).\n\n## Installation\n\n```shell\ncomposer require charcoal/translator\n```\n\nFor Charcoal projects, the service provider can be registered from your configuration file:\n\n```json\n{\n    \"service_providers\": {\n        \"charcoal/translator/service-provider/translator\": {}\n    }\n}\n```\n\n## Overview\n\n### Features\n\n#### The Translation Object\n\n[`Charcoal\\Translator\\Translation`][src-translation]\n\nThe _Translation Object_ holds the translation data for a given string in all available languages / locales.\n\n```php\n// Get a translation object from the Translator\n$translation = $container['translator']-\u003etranslation([\n    'en' =\u003e 'Hello World',\n    'fr' =\u003e 'Bonjour'\n]);\n\n// If cast to string, the default language will be used.\necho $translation;\n\n// Use ArrayAccess to get (or set) a translated value.\necho $translation['fr'];\n$translation['fr'] =\u003e 'Bonjour le monde';\n\n// To loop through all translations:\nforeach ($translation-\u003edata() as $lang =\u003e $translatedValue) {\n    // ...\n}\n```\n\n#### The Translator Service\n\n[`Charcoal\\Translator\\Translator`][src-translator-service]\n\nCharcoal's _Translator_ extends Symfony's [`Translator`](https://api.symfony.com/master/Symfony/Component/Translation/Translator.html) 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)`.\n\n#### The Locales Manager\n\n[`Charcoal\\Translator\\LocalesManager`][src-locales-manager]\n\nThe _Locales Manager_ is used to manage available locales / languages and keep track of current language.\n\n#### The Parser Script\n\n[`Charcoal\\Translator\\Script\\TranslationParserScript`][src-translation-parser]\n\nThe _Parser Script_ is used to scrape files that contain translatable content. Add the following route to your application configuration:\n\n```json\n\"scripts\": {\n    \"charcoal/translator/parse\": {\n        \"ident\": \"charcoal/translator/script/translation-parser\"\n    }\n}\n```\n\n### Service Provider\n\nThe [`TranslatorServiceProvider`][src-translator-provider] provides services and options for translating your application into different languages.\n\n#### Parameters\n\n-   **locales/config**: Configuration object for defining the available languages, fallbacks, and defaults.\n-   **locales/default-language**: Default language of the application, optionally the navigator's preferred language.\n-   **locales/browser-language**: Accepted language from the navigator.\n-   **locales/fallback-languages**: List of fallback language codes for the translator.\n-   **locales/available-languages**: List of language codes from the available locales.\n-   **locales/languages**: List of available language structures of the application.\n-   **translator/config**: Configuration object for translation service, message catalogs, and catalog loaders.\n-   **translator/translations**: Dictionary of additional translations grouped by domain and locale.\n\n#### Services\n\n-   **locales/manager**: An instance of [`LocalesManager`][src-locales-manager], used for handling available languages, their definitions, the default language, and tracks the current language.\n-   **translator**: An instance of [`Translator`][src-translator-service], that is used for translation.\n-   **translator/message-selector**: An instance of [`Symfony\\Component\\Translation\\MessageSelector`](https://api.symfony.com/master/Symfony/Component/Translation/MessageSelector.html).\n-   **translator/loader/\\***: Instances of the translation [`Symfony\\Component\\Translation\\Loader\\LoaderInterface`](https://api.symfony.com/master/Symfony/Component/Translation/Loader/LoaderInterface.html).\n\n### Configuration\n\nHere is an example of configuration:\n\n```json\n\"locales\": {\n    \"languages\": {\n        \"de\": {},\n        \"en\": {},\n        \"es\": {\n            \"active\": false\n        },\n        \"fr\": {}\n    },\n    \"default_language\": \"fr\",\n    \"fallback_languages\": [\n        \"en\", \n        \"fr\"\n    ],\n    \"auto_detect\": true\n},\n\"translator\": {\n    \"loaders\": [\n        \"xliff\",\n        \"json\",\n        \"php\"\n    ],\n    \"paths\": [\n        \"translations/\",\n        \"vendor/charcoal/app/translations/\"\n    ],\n    \"debug\": false,\n    \"cache_dir\": \"cache/translation/\",\n    \"translations\": {\n        \"messages\": {\n            \"de\": {\n                \"hello\": \"Hallo {{ name }}\",\n                \"goodbye\": \"Auf Wiedersehen!\"\n            },\n            \"en\": {\n                \"hello\": \"Hello {{ name }}\",\n                \"goodbye\": \"Goodbye!\"\n            },\n            \"es\": {\n                \"hello\": \"Hallo {{ name }}\",\n                \"goodbye\": \"Adios!\"\n            },\n            \"fr\": {\n                \"hello\": \"Bonjour {{ name }}\",\n                \"goodbye\": \"Au revoir!\"\n            }\n        },\n        \"admin\": {\n            \"fr\": {\n                \"Save\": \"Enregistrer\"\n            }\n        }\n    }\n}\n```\n\n### Middleware\n\nThe [`LanguageMiddleware`][src-translator-middleware] 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.\n\nIf you are using [charcoal/app], you can add the middleware via the application configset:\n\n```json\n\"middlewares\": {\n    \"charcoal/translator/middleware/language\": {\n        \"active\": true,\n        \"use_params\": true,\n        \"param_key\": \"hl\"\n    }\n}\n```\n\nOtherwise, with [Slim](https://github.com/slimphp/Slim), for example:\n\n```php\nuse Charcoal\\Translator\\Middleware\\LanguageMiddleware;\nuse Slim\\App;\n\n$app = new App();\n\n// Register middleware\n$app-\u003eadd(new LanguageMiddleware([\n    'default_language' =\u003e 'fr',\n    'use_params'       =\u003e true,\n    'param_key'        =\u003e 'hl',\n]));\n```\n\nThe middleware comes with a set of default options which can be individually overridden.\n\n| Setting               | Type           | Default              | Description |\n|:----------------------|:--------------:|:--------------------:|:------------|\n| **active**            | `boolean`      | `FALSE`              | Whether to enable or disable the middleware ([charcoal/app] only).\n| **default_language**  | `string`       | `null`               | The default language to use if no other languages is choosen.\n| **browser_language**  | `string`       | `null`               | The client's preferred language (`Accept-Language`).\n| **use_browser**       | `boolean`      | `true`               | Whether to use `browser_language` as the default language.\n| **use_path**          | `boolean`      | `true`               | Whether to lookup the HTTP request's URI path for a language code.\n| **excluded_path**     | `string|array` | `^/admin\\b`          | One or more RegEx patterns to ignore from localization, when matching the URI path.\n| **path_regexp**       | `string|array` | `^/([a-z]{2})\\b`     | One or more RegEx patterns to include from localization, when matching the URI path.\n| **use_params**        | `boolean`      | `false`              | Whether to lookup the HTTP request's URI query string for a language code.\n| **param_key**         | `string|array` | `current_language`   | One or more RegEx patterns to include from localization, when matching the query string keys.\n| **use_session**       | `boolean`      | `true`               | Whether to lookup the client's PHP session for a preferred language.\n| **session_key**       | `string|array` | `current_language`   | One or more RegEx patterns to include from localization, when matching the session keys.\n| **use_host**          | `boolean`      | `false`              | Whether to lookup the server host for a language code.\n| **host_map**          | `string|array` | `[]`                 | One or more RegEx patterns to include from localization, when matching the host.\n| **set_locale**        | `boolean`      | `true`               | Whether to set the environment's locale.\n\n### Helpers\n\n#### TranslatorAwareTrait\n\n[`Charcoal\\Translator\\TranslatorAwareTrait`][src-translator-helper]\n\nThe `TranslatorAwareTrait` is offered as convenience to avoid duplicate / boilerplate code. It simply sets and gets a `Translator` service property.\n\nSet with `setTranslator()` and get with `translator()`. Both are protected method. (This trait has no public interface.)\n\n## Resources\n\n* [Contributing](https://github.com/charcoalphp/.github/blob/main/CONTRIBUTING.md)\n* [Report issues](https://github.com/charcoalphp/charcoal/issues) and\n  [send pull requests](https://github.com/charcoalphp/charcoal/pulls)\n  in the [main Charcoal repository](https://github.com/charcoalphp/charcoal)\n\n[src-locales-manager]:        src/Charcoal/Translator/LocalesManager.php\n[src-translation-parser]:     src/Charcoal/Translator/Script/TranslationParserScript.php\n[src-translation]:            src/Charcoal/Translator/Translation.php\n[src-translator-helper]:      src/Charcoal/Translator/TranslatorAwareTrait.php\n[src-translator-middleware]:  src/Charcoal/Translator/Middleware/LanguageMiddleware.php\n[src-translator-provider]:    src/Charcoal/Translator/ServiceProvider/TranslatorServiceProvider.php\n[src-translator-service]:     src/Charcoal/Translator/Translator.php\n[charcoal/app]:               https://github.com/charcoalphp/app\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcharcoalphp%2Ftranslator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcharcoalphp%2Ftranslator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcharcoalphp%2Ftranslator/lists"}