PHPackages fccn/webapp-tools-translate - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Localization & i18n](/categories/localization) 4. / 5. fccn/webapp-tools-translate ActiveLibrary[Localization & i18n](/categories/localization) fccn/webapp-tools-translate =========================== Set of tools to enable translation on web applications 1.1.1(7y ago)0781MITPHPPHP >=7.0 Since Nov 6Pushed 7y ago3 watchersCompare [ Source](https://github.com/fccn/wt-translate)[ Packagist](https://packagist.org/packages/fccn/webapp-tools-translate)[ RSS](/packages/fccn-webapp-tools-translate/feed)WikiDiscussions master Synced 2mo ago READMEChangelog (3)Dependencies (6)Versions (4)Used By (1) Webapp tools - localization utilities ===================================== [](#webapp-tools---localization-utilities) This presents a set of utilities for handling multilanguage and translations for web applications. It adds Gettext support to the web application and configures Gettext with settings defined in the application configuration file. It also supports document translations and full HTML page translations. The localization utilities also provides an utility to prepare and launch xgettext via Makefile and integrates with the twig framework, via a twig filter and a utility for parsing twig templates into a format that is understandable by xgettext. The project also provides a set of web components the Slim framework: a Locale service, Localization middleware and a language switcher controller action. Installation ------------ [](#installation) You can install this collection in your project using composer: ``` composer require fccn/webapp-tools-translate ``` To complete the installation copy the contents of the **locale** and **utils** folder into **\[project\_root\]/locale** and **\[project\_root\]/utils** respectively. These folders contain the utilities for preparing and launching xgettext and parsing the twig files. ### Locale folder [](#locale-folder) The Makefile inside the locale folder prepares the content to be processed by xgettex and calls xgettext to build the .po and .mo files. It is configured to work inside the **locale** directory. It looks for php code on **\[project\_root\]/app** folder and the parsed twig templates on **\[project\_root\]/cache**. The header.po file is the base file for generating the individual .po files for each language. This file must be located in the **locale** folder. The locale folder also holds the translation files. Each language must have its own content folder. The folder must be named with the country ID (i.e pt\_PT). Each language folder must have following structure: - **\[country ID\]/** - **files/** - location for document translations - **html/** - location for full HTML page translations - **LC\_MESSAGES/** - location for Gettex translations The locale folder already contains pre built language folders for pt\_PT and en\_EN languages. ### Utils folder [](#utils-folder) If you use Twig in your web application, there will be a point where it is necessary to extract the template strings from the twig template files. Unfortunately, the xgettext utility does not understand Twig templates natively. For that reason the script in **\[project\_root\]/utils/make\_php\_cache\_files.php** converts Twig templates to PHP files, so that xgettext can be called on those files instead. The script requires Twig to have the same configurations as you define in your web application. You can edit the **\[project\_root\]/utils/TwigConfigLoader.php** file to load the required Twig extensions and filters in the **make\_php\_cache\_files.php** script. Configuration ------------- [](#configuration) The localization utilities were designed with the [FCCN's webapp skeleton project](https://github.com/fccn/webapp-skeleton.git) in mind. For this reason the script to build the .po and .mo files will search for the web application code in **\[project\_root\]/app** folder. If your application's code is stored on another location you need to edit the **\[project\_root\]/locale/Makefile** before using the Gettext utilities. The localization utilities makes use of the site configuration loader from the [Webapp Tools - common](https://github.com/fccn/wt-common) project. The following key-value pairs need to be added to the application configuration file *$c* array: ``` $c = array( ... #----- locale configuration "defaultLocale" => "pt_PT", # Setup the default locale "defaultLocaleLabel" => "PT", # and default locale label "locale_selection" => "param", # locale selection method, can be 'param' if locale to be set up by a url parameter, or 'cookie' if locale is set up by cookie #- array of available locales "locales" => array( array("label" => "GB", "locale" => "en_GB", "flag_alt" => "English flag", "language" => "English"), array("label" => "PT", "locale" => "pt_PT", "flag_alt" => "Portuguese flag", "language" => "Português"), # add other languages here.... ), "locale_textdomain" => "messages", "locale_path" => "../locale", #path of the locale folder "locale_cookie_name" => "locale", #name of the cookie to store locale information "locale_cookie_path" => "/", #relative path of the locale cookie "locale_param_name" => "lang", #name of the URL param to store locale information "request_attribute_name" => "locale", #name of the request attribute to store locale info #-twig parser configurations "twig_parser_templates_path" => "../templates", #path for twig templates folder, can be an array if you are importing templates from other projects "twig_parser_cache_path" => "../cache", #path for cache folder #activate verbose debug for debugging purposes (defaults to false) "verbose_debug" => false, ... ) ``` The twig parser supports multiple twig templates folder. You can setup multiple folders as shown below: ``` $c = array( ... twig_parser_templates_path => array( 0 => __DIR__ . '/../templates', //set the base template path //add other namespaces to twig, in the form of 'namespace' => 'path/to/twig/templates' ), ... ); ``` When configuring with twig, you need to load the same twig extensions and filters used by the web application into the twig parser. This prevents missinterpretations when parsing the twig templates. To do that edit **\[project\_root\]/utils/TwigConfigLoader.php** and add the filters and extensions to the *loadConfigs* function: ``` public function loadConfigs($twig){ .... #add the i18n extensions $twig->addExtension(new Twig_Extensions_some_extension()); #add translate filter $filter = new Twig_SimpleFilter("my filter", function($stdClassObject) { return null; }), $twig->addFilter($filter); ... } ``` You can also use preset configuration loaders like the one defined in **src/TranslateConfigurationLoader.php**. The *loadConfigs()* function in **\[project\_root\]/utils/TwigConfigLoader.php** already loads the following set of filters and extensions for localization utilities: - Twig\_Extensions\_Extension\_I18n - Twig internationalization extension - Twig\_Extensions\_Extension\_Intl - Twig date and time localization extension - Translate filter ### Integration with Slim [](#integration-with-slim) To enable global access to locale information you can add an instance of Fccn\\Lib\\Locale as a service - the Locale service - to your Slim application. The example below shows how to add the service to the Slim container and create a global *lang* variable in the view: ``` $app = new \Slim\App(...); // Fetch DI Container $container = $app->getContainer(); $container['locale'] = function ($cnt) { $locale = new Fccn\Lib\Locale(); //add global lang var $cnt->view->getEnvironment()->addGlobal('lang', $locale); return $locale; }; ``` The localization utilities provides a Slim middleware to add localization to your web application - the Localization middleware. This middleware uses the Locale service described above. For a better integration you need to configure the Locale with middleware integration. The example below shows how to add the Localization middleware to the Slim application: ``` $app = new \Slim\App(); //get container $container = $app->getContainer(); //Create the locale service $container['locale'] = function ($cnt) { //set Locale to middleware integration $locale = new Fccn\Lib\Locale(array('slim_middleware' => true)); //add global lang var $cnt->view->getEnvironment()->addGlobal('lang', $locale); return $locale; }; //Add locale middleware $app->add(new Fccn\WebComponents\LocaleMiddleware($container['locale'])); ``` To switch between languages you can use the language switcher controller action. The path for selecting a new language must be defined as `//{lang}` where *lang* is the language label (case insensitive) defined in the locales array in the configuration file (*i.e. mysite.pt/setlang/pt, sets language to Portuguese*). The following example shows how to define the language switching route for the path `/utils/setlang/{lang}` with the language switcher controller action: ``` $app = new \Slim\App(); $app->get('/utils/setlang/{lang}', Fccn\WebComponents\SwitchLanguageAction::class); ``` ### Adding more languages [](#adding-more-languages) To create additional languages do as follows inside the **locale** folder: 1. Add a new directory with country ID. `mkdir -p es_ES/LC_MESSAGES` 2. Copy the header file to the directory. `cp header.po es_ES/LC_MESSAGES/messages.po` 3. Create the directories to hold the rest of the files to translate. `mkdir es_ES/files; mkdir es_ES/html` 4. Clean cache. `make clean` 5. Update message files. `make` 6. Edit the po file and translate it. `vi es_ES/LC_MESSAGES/messages.po` 7. Do not forget to assign language, i.e. **"Language: es\_ES\\n"** 8. Update message files. **make** 9. Edit the application configuration file, add the new language to the *locales* array. Usage ----- [](#usage) The following shows the different use cases for the language utilities. ### Translate HTML content [](#translate-html-content) Put the translated HTML snippets on **locale/\[country\_id\]/html/** folder. The snippets must have the same name on all language folders. For example, to print the en\_EN HTML content from a snippet on **locale/en\_EN/html/my\_snippet.html**, whose contents are: ``` This is a tranlated html snipped ``` you should do as follows, after setting the locale to en\_EN: ``` $locale = new \Fccn\Lib\Locale(); $html_content = $locale->getHtmlContent('my_snippet'); echo $html_content ``` this in turn prints out ``` This is a tranlated html snipped ``` ### Translate text content [](#translate-text-content) Put the translated snippets on **locale/\[country\_id\]/files/** folder. The snippets must have the same name on all language folders. For example, to print the en\_EN content from a snippet on **locale/en\_EN/files/my\_snippet.txt**, whose contents are: ``` This is a sample snippet of translated text ``` you should do as follows after setting the locale to en\_EN: ``` $locale = new \Fccn\Lib\Locale(); $text_content = $locale->getFileContent('my_snippet'); echo $text_content ``` this in turn prints out ``` This is a sample snippet of translated text ``` It is possible to include variables in the translated text snippets. The variables are represented inside brackets {} (i.e, {name}). For example if you want the snippet to adapt to the user's name you can define en\_EN version of the snippet in **locale/en\_EN/files/hello\_user.txt**: ``` Hello {user_name}. ``` To get the content with the instantiated variable you should do as follows after setting the locale to en\_EN: ``` $locale = new \Fccn\Lib\Locale(); $text_content = $locale->processFile('hello_user',array("{user_name}" => "New User")); echo $text_content ``` this in turn prints out ``` Hello New User ``` ### Gettext translations [](#gettext-translations) To add translatable content on the application code write the content you want to translate inside *\_()* (i.e *\_('Translate me')*). To add translatable content on twig templates load the provided translation filters to twig: ``` $twig = new Twig_Environment(); \Fccn\Lib\TranslateConfigurationLoader::loadTwigConfigs($twig); ``` Then on the twig templates just use the *trans* tag: ``` {% trans "Translatable content" %} ``` Each time you add content to the application and templates you need to update the translations: 1. go to the **locale** directory and run `make`. 2. This will update with new content the .po file on each of LC\_MESSAGES folder inside the individual language directory. 3. Edit the .po files for each language and add the missing translations. 4. run `make` again on the **locale** folder to update the compiled translations in the .mo files. To refresh the translated contents run `make clean && make` on the **locale** folder. Testing ------- [](#testing) This project uses codeception for testing. To run the tests call `composer test` on the root of the project folder. Contributing ------------ [](#contributing) Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct, and the process for submitting pull requests to us. Versioning ---------- [](#versioning) We use [SemVer](http://semver.org/) for versioning. For the versions available, see the [tags on this repository](https://github.com/fccn/wt-translate/tags). License ------- [](#license) This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details ### Health Score 27 — LowBetter than 49% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity9 Limited adoption so far Community7 Small or concentrated contributor base Maturity60 Established project with proven stability How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~169 days Total 3 Last Release 2767d ago PHP version history (2 changes)1.0.1PHP >=5.5.0 1.1PHP >=7.0 ### Community Maintainers ![](https://www.gravatar.com/avatar/6efba5d9e65dd75d8c1abb0fc271d6516d58df27c558da0e14ef1ed0a8b1cf35?d=identicon)[pcosta](/maintainers/pcosta) --- Tags fccnwebapp-toolsgettex ### Code Quality TestsCodeception ### Embed Badge ![Health badge](/badges/fccn-webapp-tools-translate/health.svg) ``` [![Health](https://phpackages.com/badges/fccn-webapp-tools-translate/health.svg)](https://phpackages.com/packages/fccn-webapp-tools-translate) ``` ### Alternatives [symfony/translation Provides tools to internationalize your application 6.6k836.5M2.0k](/packages/symfony-translation)[nesbot/carbon An API extension for DateTime that supports 281 different languages. 169661.4M4.8k](/packages/nesbot-carbon)[joedixon/laravel-translation A tool for managing all of your Laravel translations 717911.4k11](/packages/joedixon-laravel-translation)[illuminate/translation The Illuminate Translation package. 6936.4M491](/packages/illuminate-translation)[lajax/yii2-translate-manager Translation management extension for Yii 2 227578.8k13](/packages/lajax-yii2-translate-manager)[larswiegers/laravel-translations-checker Make sure your laravel translations are checked and are included in all languages. 256423.2k2](/packages/larswiegers-laravel-translations-checker) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)