PHPackages lehadnk/translation-merge-tool - 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. lehadnk/translation-merge-tool ActiveLibrary[Localization & i18n](/categories/localization) lehadnk/translation-merge-tool ============================== The tool for generation and merge of translation files. 1.6.4(1y ago)229PHPPHP ^8.1 Since Oct 12Pushed 1y ago1 watchersCompare [ Source](https://github.com/lehadnk/translation-merge-tool)[ Packagist](https://packagist.org/packages/lehadnk/translation-merge-tool)[ RSS](/packages/lehadnk-translation-merge-tool/feed)WikiDiscussions master Synced 1mo ago READMEChangelogDependencies (5)Versions (50)Used By (0) Introduction ============ [](#introduction) i18n\_mrg is the helper tool that scans your project's codebase for translated strings and synchronizes translations with a popular translation tool named [Weblate](https://weblate.org) and back. Installation ============ [](#installation) The software you need to install the translation merge tool: - PHP >= 7.0 - [Composer](https://getcomposer.org/download/) package manager - [GNU Gettext](https://www.gnu.org/software/gettext/) package (already installed on macOS and most Linux distributions) - NodeJS >= 6.0 (for JS projects) - [i18next converter](https://github.com/i18next/i18next-gettext-converter) (if you use i18next for your js project) You require php>=8.1 to run the software. Also, you require to have a PHP packet manager (composer), which you may get [here](https://getcomposer.org/download/). Run the following command to install the tool: ``` composer global require lehadnk/translation-merge-tool ``` Running the tool ================ [](#running-the-tool) Run the following command under your project root: ``` i18n_mrg ``` Project setup ============= [](#project-setup) First, you need to prepare your codebase to work with i18n\_mrg: 1. Configure your project to work with translation files. We'd suggest you use [GNU gettext](https://www.gnu.org/software/gettext/) format, but i18n\_mrg could also compile JSON files as well if you prefer, which works better for web applications. You need to set up a directory in your project and store your translation files in it, naming each subfolder with the language code you're planning to use. Example file tree structure: ``` /i18n/en_GB/messages.po /i18n/de_DE/messages.po /i18n/zh_CN/messages.po ``` 2. Use the wrapper function named `__()` to mark your translation strings. Implement the function to return the corresponding string from your storage, e.g.: ``` public class i18nService { private static translationStrings; public static String __(string text, HashMap placeholders) { var translatedString = i18nService.translationStrings.get("de_DE").get(text); StrSubstitutor sub = new StrSubstitutor(placeholders, "%", "%"); return sub.replace(translatedString); } } ``` ``` import static i18n.I18nFacade.__; public class ScoreHandler { public UserResponse getScore() { var placeholders = new HashMap(); placeholders.put("score", 16); var response = new UserResponse(); response.message = __("You have %score% points", placeholders); // Sie haben 16 Punkte return response; } } ``` 3. Add `.translate-config.json` to your project root. The example contents of the file: ``` { "configVersion": "1.3.0", "components": [ { "name": "default", "includePaths": [ "app/", "resources/" ], "excludePaths": [], "translationFileName": "resources/lang/i18n/{localeName}/LC_MESSAGES/default.po", "weblateProjectSlug": "crm", "weblateComponentSlug": "main" } ], "vcs": "bitbucket", "bitbucketUsername": "bitbucket@user.com", "bitbucketPassword": "password", "vcsRepository": "company/crm-project", "vcsAuthToken": "token", "translationBranchName": "translation", "weblateServiceUrl": "http://weblate.service.com", "weblateAuthToken": "token" } ``` 4. Next, define the translation branch in your repository. Usually, you want it to be managed by translation tools (i18n\_mrg and Weblate) only, and never touch it: `git checkout -b translations && git push --set-upstream origin translations` 5. Set up the Weblate platform and define the [component](https://docs.weblate.org/en/latest/admin/projects.html) for your project. 6. Now run `i18n_mrg` to scan your project for translation strings and initially upload them to Weblate. i18n\_mrg will parse your codebase for every string wrapped in \_\_() decorator and add it to translation files, the pull updates from Weblate automatically. Developer workflow ================== [](#developer-workflow) For developers working with `i18n_mrg` on your project, I'd suggest the following workflow: 1. When you're about to be done with your working branch, which contains translation strings, run `i18n_mrg` and push new translation strings to Weblate. 2. Notify the person in your team responsible for handling translation that new strings are added to Weblate. 3. Once translations are done, run `i18n_mrg` again to pull translated strings from Weblate and add updated translated files to your branch. In big teams, you may also want translations files compilation to be a part of your CI cycle. Updating the tool ================= [](#updating-the-tool) ``` composer global update lehadnk/translation-merge-tool ``` Handling authorization tokens ============================= [](#handling-authorization-tokens) To use the tool with various VCS providers, you must set up authorization. ### Gitlab [](#gitlab) 1. Create the key using your profile settings > Access Tokens. 2. Your key must have the next scopes: api, read\_repository, write\_repository 3. Export your token to I18N\_MRG\_GITLAB\_AUTH\_TOKEN env variable: `export I18N_MRG_GITLAB_AUTH_TOKEN=` ### Github [](#github) 1. Goto Settings > Developer Settings > Personal access tokens 2. Create a token with scope: repo 3. Export your token to I18N\_MRG\_GITHUB\_AUTH\_TOKEN env variable: `export I18N_MRG_GITHUB_AUTH_TOKEN=` ### BitBucket [](#bitbucket) 1. Go to repository settings 2. Issue the repository access token with read/write permissions in the "Access Tokens" section 3. Place your token in I18N\_MRG\_BITBUCKET\_AUTH\_TOKEN env variable: `export I18N_MRG_BITBUCKET_AUTH_TOKEN=` How to add it to the project ============================ [](#how-to-add-it-to-the-project) First, you need to create a`.translate-config.json` configuration file under the project's root. Example contents of the config file: Troubleshooting =============== [](#troubleshooting) Some Mac users reported that they had issues with the gettext tool installed through Brew. Unlinking and linking it again resolves the issue: ``` brew unlink gettext && brew link gettext ``` ### Health Score 37 — LowBetter than 83% of packages Maintenance31 Infrequent updates — may be unmaintained Popularity10 Limited adoption so far Community9 Small or concentrated contributor base Maturity83 Battle-tested with a long release history Bus Factor1 Top contributor holds 99.1% of commits — single point of failure 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 ~44 days Recently: every ~0 days Total 48 Last Release 711d ago PHP version history (4 changes)1.0.6PHP ^7.0 1.2.0PHP ^7.1 1.2.5PHP ^7|^8 1.4.0PHP ^8.1 ### Community Maintainers ![](https://www.gravatar.com/avatar/a282915eb2e29b5d377e8f18908b3976b4b67808684c32db7a002ea5adbd2c96?d=identicon)[lehadnk](/maintainers/lehadnk) --- Top Contributors [![lehadnk](https://avatars.githubusercontent.com/u/6454611?v=4)](https://github.com/lehadnk "lehadnk (109 commits)")[![mexoboy](https://avatars.githubusercontent.com/u/1552138?v=4)](https://github.com/mexoboy "mexoboy (1 commits)") ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/lehadnk-translation-merge-tool/health.svg) ``` [![Health](https://phpackages.com/badges/lehadnk-translation-merge-tool/health.svg)](https://phpackages.com/packages/lehadnk-translation-merge-tool) ``` ### Alternatives [tio/laravel Add this package to localize your Laravel application (PHP, JSON or GetText). 170318.5k](/packages/tio-laravel)[vemcogroup/laravel-translation Translation package for Laravel to scan for localisations and up/download to poeditor 135304.0k2](/packages/vemcogroup-laravel-translation)[mage-os/module-automatic-translation Automatic AI content translation for Mage-OS. 277.1k](/packages/mage-os-module-automatic-translation)[acclaro/translations Easily launch and manage multilingual Craft websites without having to copy/paste content or manually track updates. 1229.5k](/packages/acclaro-translations) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)