{"id":20310145,"url":"https://github.com/phpro/phpro-mage2-module-translations","last_synced_at":"2025-04-11T15:40:59.846Z","repository":{"id":39995638,"uuid":"453021538","full_name":"phpro/phpro-mage2-module-translations","owner":"phpro","description":"Translation module for Magento 2","archived":false,"fork":false,"pushed_at":"2024-03-28T14:35:37.000Z","size":687,"stargazers_count":12,"open_issues_count":3,"forks_count":9,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-04-28T19:43:34.954Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"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/phpro.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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-01-28T10:12:46.000Z","updated_at":"2024-07-05T16:15:21.444Z","dependencies_parsed_at":"2024-07-05T16:15:18.517Z","dependency_job_id":"38ff090a-08ca-42ce-9a55-d3029f3d182d","html_url":"https://github.com/phpro/phpro-mage2-module-translations","commit_stats":{"total_commits":67,"total_committers":6,"mean_commits":"11.166666666666666","dds":"0.28358208955223885","last_synced_commit":"4187ea96a92a1b0f878bf04842e758fe6d35a599"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phpro%2Fphpro-mage2-module-translations","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phpro%2Fphpro-mage2-module-translations/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phpro%2Fphpro-mage2-module-translations/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phpro%2Fphpro-mage2-module-translations/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/phpro","download_url":"https://codeload.github.com/phpro/phpro-mage2-module-translations/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248432932,"owners_count":21102467,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":[],"created_at":"2024-11-14T17:30:11.794Z","updated_at":"2025-04-11T15:40:59.826Z","avatar_url":"https://github.com/phpro.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"![](https://github.com/phpro/phpro-mage2-module-translations/workflows/.github/workflows/grumphp.yml/badge.svg)\n\n![](https://shields.io/badge/Hyv%C3%A4_Theme-Compatible---?style=for-the-badge\u0026labelColor=F6F7FF\u0026color=0B23B9\u0026logoColor=0B23B9\u0026logo=data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjQiIGhlaWdodD0iMjQiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+PHBhdGggZD0iTTkuNjI1IDkuNzdjMS4zNTUtMS4wNDcgMy4wMDgtMS43MDcgNC44NjctMS43MDcgMy44MDUgMCA3LjUwOCAyLjM2NyA3LjUwOCA4LjQzM1YyNGgtNC44Njd2LTcuNTA0YzAtMy4xMjktMS41MjgtNC4zMDgtMy42MTMtNC4zMDgtMS43MjMgMC0yLjk3My45Ni0zLjY2OCAxLjk3NlYyNEg0Ljk2NVY0LjUzMUgyTDMuNTYzIDBoNi4wNjJ2OS43N3pNMTYuNjQgMEgyMmwtMS41NyA0LjUzMWgtNS4zNTJMMTYuNjQgMHoiLz48L3N2Zz4K)\n\n# Translation module for Magento 2\n\nThe `Phpro_Translations` module helps you to manage translations via the Magento backend.\n\n## Features\n* Simple backend CRUD to manage translations\n* Single and multi-inline editing via the grid-overview\n* Import and export via CSV files via CLI \n* Import and export via default Magento import/export functionality\n* Prepare new translations via data patch scripts\n* (Re)generate frontend translations (JSON translation files) via CLI and backend\n\n## Installation\n```\ncomposer require phpro/mage2-module-translations\n```\n\n## End user documentation\n[Download the end user documentation (PDF)](./resources/phpro-translation-module-EUD.pdf)\n\n## Usage (technical)\n\n### Locales \nAll locales must be defined in an ISO format. Locale = ISO-639 (language)  + \"_\" + ISO-3166 (country). \n\nExamples of locales: en_US, nl_BE, nl_NL, fr_BE, de_DE, ...\n\n### Import and export\n\n#### Import Magento translation CSVs\n\nCSV structure must be (key, value):\n```\n\"Transkey 1\",\"Transvalue 2\"\n\"Transkey 2\",\"Transvalue 2\"\n...\n```\nUse the `phpro:translations:import` command to import a CSV file for a given locale. Duplicate records are skipped and no updates are applied. \n```\nbin/magento phpro:translations:import /path/to/cs_CZ/cs_CZ.csv cs_CZ --clear-cache\n```\nOutput:\n```\nImporting CSV file /path/to/cs_CZ/cs_CZ.csv for locale cs_CZ\n#created: 193\n#skipped: 4\n#failed: 0\nCaches cleared: full_page, block_html, translate\nDone!\n```\n\n#### Export to CSV\n\nUse the `phpro:translations:export` command to export database translations to a CSV file for one or more locales. Separate multiple locales with a space. The exported CSV file is written in the `var/translations` folder of Magento. \n```\nbin/magento phpro:translations:export nl_BE cs_CZ\n```\nOutput:\n```\nExporting translations to CSV file\nCsv file: /path/to/var/translations/20190531_085402_export_nl_BE_cs_CZ.csv\nTotal written rows: 390\nDone!\n```\nCSV structure:\n```\n\"New Account\",\"Nieuwe account\",nl_BE\n\"My Wish List\",\"Mijn verlanglijst\",nl_BE\n\"New Account\",\"Nový účet\",cs_CZ\n\"My Wish List\",\"Mé oblíbené\",cs_CZ\n...\n```\n\n#### Import CSV (including locale)\nYou can use the exported CSV file(s) to import on another environment. For example you can prepare new translations on a staging environment and import them later on a production environment. \n\nCSV structure must be (key, value, locale):\n```\n\"Transkey 1\",\"Transvalue 2\",nl_BE\n\"Transkey 2\",\"Transvalue 2\",nl_BE\n\"Transkey 1\",\"Transvalue 2\",fr_BE\n\"Transkey 2\",\"Transvalue 2\",fr_BE\n...\n```\nUse the `phpro:translations:import-full` command to import a CSV file. Duplicate records are skipped and no updates are applied. \n```\nbin/magento phpro:translations:import-full /path/to/full_import_nl_BE_cs_CZ.csv --clear-cache\n```\nOutput:\n```\nImporting CSV file /path/to/full_import_nl_BE_cs_CZ.csv\n#created: 10\n#skipped: 380\n#failed: 0\nCaches cleared: full_page, block_html, translate\nDone!\n```\n\n#### Import via backend\nGo to System → (Data Transfer) → Import to create or update translations based on a CSV file. Please reach out our end user documentation. \n\n### Re-generate frontend translations\nGenerating/re-generating frontend translation will generate JSON file(s) which includes all the frontend/JS translations.\nThese files are stored in the `pub/media/phpro_translations` directory in their related theme/locale subdirectory.\n\n#### Via backend\n- Go to \"Translations -\u003e Generate frontend translations\" in the admin. Select \"all store views\" or select specific ones. Click the button \"Generate translations files\".\n- Clear full page and block html caches via \"System -\u003e Cache Management\".\n- Also check the end user documentation\n\n#### Via CLI\n- Use the `phpro:translations:generate-frontend-translations` command to re-generate new JSON file(s) \n- Make sure you clean full_page and block_html cache manually afterwards to apply and enable the newest translation JSON file for the storefront.\n\n**Re-generate for single store view**\n\nSpecify the `storeId` argument to re-generate for specific store view (locale). Use the `bin/magento store:list` command to show the store IDs.  \n```\nbin/magento phpro:translations:generate-frontend-translations 5\n```\n\n**Re-generate for all**\n\nLeave the `storeId` argument empty to re-generate for all store views.\n```\nbin/magento phpro:translations:generate-frontend-translations\n```\n\n#### During build process\nWe recommend to re-generate all frontend translations during your build process with `phpro:translations:generate-frontend-translations` after the `setup:upgrade --keep-generated` step and just before deactivating maintenance.\n\n#### Browser cache optimizations\nThe translations JSON files are stored in the directory `pub/media/phpro_translations` with a specific version string. \nYou can choose to have a these files optimally cached by browsers by configuring the Cache-Control header. A ngnix example below: \n```\nlocation /media/phpro_translations/ {\n    add_header X-Frame-Options \"SAMEORIGIN\";\n    add_header Cache-Control \"public\";\n    expires +1y;\n}\n```\n\n### Collect translations from code base\nUse the `phpro:translations:prepare-keys` command to collect translations phrases from the code base and prepare them. This will create a translation for every available locale.\n\n### Add translations during development\nTo prepare, create or delete translations you can inject `\\Phpro\\Translations\\Api\\TranslationDataManagementInterface` as dependency into your data patch script of your module. \n\n#### Prepare\nAdd the translation key for all enabled locales of the Magento instance. If default translation is not set, the translation key will be used as default translation.\n\n```\nuse Magento\\Framework\\Setup\\Patch\\DataPatchInterface;\nuse Magento\\Framework\\Setup\\Patch\\NonTransactionableInterface;\nuse Phpro\\Translations\\Model\\TranslationDataManagement;\n\nclass HelloWorldTranslations implements DataPatchInterface, NonTransactionableInterface\n{\n    private TranslationDataManagement $translationDataManagement;\n    \n    public function __construct(\n        TranslationDataManagement $translationDataManagement\n    ) {\n        $this-\u003etranslationDataManagement = $translationDataManagement;\n    }\n\n    public function apply() \n    {\n        $this-\u003etranslationDataManagement-\u003eprepare('Hello world!');\n        $this-\u003etranslationDataManagement-\u003eprepare('Welcome %1', 'Hello %1');\n        // other translation keys here...\n    }\n}    \n```\n#### Create\nAdd a translation for given locales.\n```\nuse Magento\\Framework\\Setup\\Patch\\DataPatchInterface;\nuse Magento\\Framework\\Setup\\Patch\\NonTransactionableInterface;\nuse Phpro\\Translations\\Model\\TranslationDataManagement;\n\nclass HelloWorldTranslations implements DataPatchInterface, NonTransactionableInterface\n{\n    private TranslationDataManagement $translationDataManagement;\n\n    public function __construct(\n        TranslationDataManagement $translationDataManagement\n    ) {\n        $this-\u003etranslationDataManagement = $translationDataManagement;\n    }\n\n    public function apply() \n    {\n        $this-\u003etranslationDataManagement-\u003ecreate('Hello world!', 'Hallo wereld!!!', ['nl_NL', 'nl_BE']);\n        $this-\u003etranslationDataManagement-\u003ecreate('Hello world!', 'Hello world!!!', ['en_US']);\n        // other translation keys here...\n    }\n}\n```\n#### Delete\nDelete a translation for given translation key and locale(s). In case no locales are given, all enabled locales will be used for deletion.\n```\nuse Magento\\Framework\\Setup\\Patch\\DataPatchInterface;\nuse Magento\\Framework\\Setup\\Patch\\NonTransactionableInterface;\nuse Phpro\\Translations\\Model\\TranslationDataManagement;\n\nclass DeleteHelloWorldTranslations implements DataPatchInterface, NonTransactionableInterface\n{\n    private TranslationDataManagement $translationDataManagement;\n\n    public function __construct(\n        TranslationDataManagement $translationDataManagement\n    ) {\n        $this-\u003etranslationDataManagement = $translationDataManagement;\n    }\n\n    public function apply() \n    {\n        $this-\u003etranslationDataManagement-\u003edelete('Hello world!');\n        $this-\u003etranslationDataManagement-\u003edelete('Welcome %1', ['nl_BE', 'nl_NL']);\n        // other translation keys here...\n    }\n}\n```\n## PWA\nThe checkbox \"frontend\" could be used to mark translations that need to be exported to a PWA installation.\nWith a rest API call, the translations can be fetched and stored in the PWA translations files.\n\n### API call that can be used in build scripts\n```\ncurl -G -k -H \"Authorization: Bearer \u003ctoken\u003e\" --data-urlencode \"searchCriteria[filter_groups][0][filters][0][field]=frontend\" --data-urlencode \"searchCriteria[filter_groups][0][filters][0][value]=1\" --data-urlencode \"searchCriteria[filter_groups][1][filters][0][field]=locale\" --data-urlencode \"searchCriteria[filter_groups][1][filters][0][value]=\u003clocale\u003e\" \u003cMagento base url\u003erest/V1/phpro-translations/translation/search\n```\n\n## Hyvä\n\nInstall the Hyvä compatibilty module. Minimum version is 1.2.3.\n```\ncomposer require hyva-themes/magento2-phpro-translations\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphpro%2Fphpro-mage2-module-translations","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphpro%2Fphpro-mage2-module-translations","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphpro%2Fphpro-mage2-module-translations/lists"}