Convert PHP language files to JSON translations

Use it to move a plugin from PHP language files to JSON translations, with every language key in the code replaced by its string and each language carried across.

  • Tested with Opus 5.5
  • October CMS 4.x
  • Plugins & Extending
  • By the October CMS team
  • Added on Nov 21, 2026
Prompt
You are helping me convert the language files of a plugin for October CMS 4, which runs on Laravel. Plugin: [Author.Plugin, eg: Acme.Library] Default language: [locale, eg: en] Move the plugin from PHP language files, eg: lang/en/lang.php, to JSON language files, and change nothing else about how it works. In a JSON file the key is the string in the default language and the value is its translation, eg: lang/fr.json: ```json { "Books": "Livres", "Hello :name": "Bonjour :name" } ``` 1. Read every PHP language file of the default language. There can be several, eg: lang/en/lang.php and lang/en/validation.php, and their keys can be nested. 2. Find every place the plugin uses one of those keys, eg: acme.library::lang.books.title, in PHP, YAML, backend views, Twig and JavaScript, and replace it with the string itself: - In PHP, call the helper with double quotes, eg: __("Books"), and escape a double quote or dollar sign inside the string. Twig uses the same function, eg: {{ __("Books") }}. - In a view, <?= e(trans('...')) ?> becomes <?= __("Books") ?>. Keep the e() when the string sits inside an HTML attribute or takes values. - In YAML, write the plain string, eg: label: Books, and quote it where YAML needs it. - Write the plain string in double quotes, without the helper, where October CMS translates it for you: the registration methods in Plugin.php, componentDetails and defineProperties, and a model's $customMessages and $attributeNames. 3. Keep each string exactly as it is, with its typos, HTML and placeholders such as :name, %s and {name}. Keep the code around it too, so sprintf(trans('...'), $count) becomes sprintf(__("..."), $count). 4. Where a key is built at run time, eg: trans('acme.library::lang.status.'.$code), write out each string in full, such as with a match on the code, so every string appears in the code. 5. Write the JSON file for the default language, eg: lang/en.json, with one entry for each different string you used, where the key and the value are the same. Follow the order of the PHP files. Indent with four spaces, and write slashes and accented characters as they are. 6. Write a JSON file for every other language folder, eg: lang/fr.json from lang/fr, with the default language string as the key and that language's translation as the value. Leave out a string the language has no translation for. 7. Delete the PHP language files and their folders. Only replace this plugin's language keys. The same prefix names its mail templates and views, eg: acme.library::mail.welcome, and those stay. Keys of another plugin or of October CMS, eg: backend::lang.form.save, stay too. Do not reword or fix a string, and do not translate anything yourself. Change no code beyond what the conversion needs. Check your work at the end. Search the plugin for the old key prefix and explain anything left. Confirm that every string in __() and every plain string you wrote is in the default JSON file, and that the file holds nothing else. Run php -l on each PHP file you changed, and make sure each YAML and JSON file parses. Finish with these lists: - Keys that nothing used, which you left out. - Keys the code uses that have no string, which you left as they were. - Strings with two different translations in one language, where you kept the first. - Strings that components or mail templates show to visitors. October CMS loads a plugin's JSON files in the backend only, so a site translates those in its theme. - Typos and mistakes you noticed in the strings.
How to use

Fill in the plugin code, eg: Acme.Library, then paste it into an AI assistant that can edit the files in your project. Commit your work first, so the conversion is one change you can review and undo.

The default language is the one the strings were first written in, usually en. Its strings become the keys of every JSON file, so lang/en.json maps each string to itself and lang/fr.json maps the same strings to French.

The PHP language files are deleted at the end. A theme or another plugin that prints one of the old keys needs the same change.

A plugin's JSON files are loaded in the backend only. Strings that a component shows to visitors are translated in the theme's own language files, and the assistant lists those strings for you.

Check these in the result:

  • The backend pages show text everywhere. A key on screen, eg: acme.library::lang.books.title, is a string that was missed.
  • Labels with a colon, quotes or HTML still look right in forms and lists.
  • With another language chosen in Backend Preferences, the labels are translated.
  • A search of the plugin for ::lang. finds only what the assistant explained.
  • Every entry of lang/en.json has the same key and value, and the other files use the same keys.

Good follow-up prompts:

  • "Add a test that fails when a string passed to __() is missing from lang/en.json."
  • "Change the %s placeholders to named ones such as :count, in the code and in every language file."
  • "Add the strings shown to visitors to my theme's language files."

Was this prompt helpful?

Still need help?
October Forum

Community members share experiences, ask questions and exchange tips.

Discord

Talk with other October CMS developers in real time.

Custom Development

Hire the October CMS team to work on your website.

Contact Us

For bug reports and help with this website. See the roadmap or submit an idea on the Portal.