Other/Alternative Localization docs?

I am wondering if anyone might know of and share a deeper dive than what’s in the Book about using localization in CakePHP (particularly for someone who has never done any kind of localization work before)?

I’m specifically looking to get started with something very simple… actually, not looking just yet for supporting more than one language but instead seeking to use it as a means to switch/customize the vocabulary used in my app.

For example: to seamlessly and easily support changing the way a model/controller name is displayed across the entire application depending on user preference — as if I designed my app for “Cars” and decide I want to support an alternative “Autos” instead.

Knowing full well that supporting other languages in the future also means changing “Cars” to whatever word needed, I would like to play around with that right away but simply as a means to make it easy to swap certain wordings I choose in the GUI without having to search and replace on the backend or refactor, etc. (and also as a way to retain the option to support all variations instead of committing to one).


what do you mean by “deeper dive”? For someone who has done nothing with i18n/localization before the book description can be very extensive (“Creating Message Parsers”, “Creating Generic Translators”, etc…) and if you haven’t done localization before it can be rather confusing.

But after a while the i18n/localization in CakePHP 4 very simple for me.
Do you know the i18n tool? I18N Tool - 4.x - very helpfull:

At the beginning of the development I use everywhere the global __() function: e.g. __(“Das ist eine Überschrift”)
Even without the translation file this text is shown. With the i18n tool
I create a PO file later and translate it with the program https://poedit.net/.
Partly automatically by a translation service integrated in PoEdit.
The generated files in the other languages will be stored where CakePHP wants to have it according to the docu/book.

I then adjust the “defaultLocale” to “de” and activate the middleware (Internationalization & Localization - 4.x)
so that the application automatically switches to the correct language when a browser with a different
language identifier in the HTTP request calls the CakePHP application.

In addition, a user who logs in can select the language on login. The language is stored in the session and is read in “AppController” in “beforeFilter” from the session which sets the language on runtime with

Maybe I meant “for dummies” and not “deeper dive”

My problem is I don’t understand half of what it’s talking about. It seems like it might have requirements beyond what is found in a straight up CakePHP installation. So, for instance, unlike how I can edit my form templates, where and how to keep alternate languages is unclear to me.

It’s not even clear that what I seek is supported. Is localization something that depends on some external, standardized translation library? Or is localization simply a collection of flat documents I create and maintain on my own and Cake can lookup the “version” of any given string from there?


where and how to keep alternate languages is unclear to me.

Under “resources/locales/” + directory name of your translation e.g.
See: Internationalization & Localization - 4.x

Is localization something that depends on some external, standardized translation library?

Translation files (".po" and “.pot”) are textfiles (You can open it with any text editor) in
the so called “GetText portable object”-Format. That is a standard format - not standard library.

Some basic information about GetText portable objects copy + paste from

GetText Portable Object (PO) files are the industry standard for multilingual websites in PHP.

POT – Portable Object Template. This is the file that you get when you extract texts from the application. Normally, you send this file to your translators.
PO – Portable Object. This is the file that you receive back from the translators. It’s a text file that includes the original texts and the translations.
MO – Machine Object. The MO file includes the exact same contents as PO file. The two files differ in their format. While a PO file is a text file and is easy for humans to read, MO files are compiled and are easy for computers to read. Your web server will use the MO file to display the translations.

PO and POT files are essentially the same. The difference is in the intended use. This is why the two files have different extensions (.pot versus .po).

A tool that scans your PHP source will produce a .pot file. This file includes only the original texts, which need translation.

Keep in mind: that type of tool does CakePHP already have: I18N Tool - 4.x

Or is localization simply a collection of flat documents

It is a collection of text documents in a folder structure - see above.

…I create and maintain on my own

Yes - no one knows your application better than you :slight_smile:

Just try it out like this:

Take a view of your application and replace some string in the HTML Code with e.g.

<h1><?= __("Hinweis") ?></h1>

Reload the view in the Browser: you will see the german word “Hinweis”

Now run “bin/cake i18n extract” See: I18N Tool - 4.x

A file is generated under “resources/locales/default.pot.” - in this simple case it will contain something like this:

# LANGUAGE translation of CakePHP Application
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: PROJECT VERSION\n"
"POT-Creation-Date: 2020-04-18 18:46+0000\n"
"PO-Revision-Date: YYYY-mm-DD HH:MM+ZZZZ\n"
"Last-Translator: NAME <EMAIL@ADDRESS>\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=utf-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Plural-Forms: nplurals=INTEGER; plural=EXPRESSION;\n"

msgid "Hinweis"
msgstr ""

Now create a folder unter “resources/locales/en/” and copy the “default.pot”
into that folder and rename it to “default.po”.
Open this new file and add the english word for “Hinweis” behind the “msgstr”-Key:

msgid “Hinweis”
msgstr “Notice”

Go to the “config/app.php” and set ‘defaultLocale’ => ‘en’ or ‘defaultLocale’ => env(‘APP_DEFAULT_LOCALE’, ‘en’)

Reload your Page/View - You should see the word “Notice” now.

This was a quick run through to try and understand.

You can also take some of Cakes translation files from here localized/resources/locales at master · cakephp/localized · GitHub
to translate the standard / default messages from the Cake framework for your language.

1 Like

Wow. Thank you for all that! I’m going to play around with it and see what I can learn.

Very grateful.