{"id":8397,"date":"2026-09-24T07:58:36","date_gmt":"2026-09-24T07:58:36","guid":{"rendered":"https:\/\/poeditor.com\/blog\/?p=8397"},"modified":"2026-09-24T08:07:33","modified_gmt":"2026-09-24T08:07:33","slug":"cakephp-localization","status":"publish","type":"post","link":"https:\/\/poeditor.com\/blog\/cakephp-localization\/","title":{"rendered":"CakePHP localization: How to translate a CakePHP app with i18n"},"content":{"rendered":"\n
\"\"<\/figure>\n\n\n\n

CakePHP relies on conventions to keep configuration simple. For example, if you name a table todo_lists<\/code>, the framework expects the related table class, controller and template folder to follow the same naming pattern. This makes it easier to navigate an unfamiliar CakePHP project. <\/p>\n\n\n\n

These conventions do not cover the language used by the application. If you are building for multiple markets, labels, buttons and messages need to be translated, while dates and numbers need to follow the conventions of each locale. Internationalization (i18n) prepares the application for translation, while localization (l10n) applies the translations and locale-specific formats. <\/p>\n\n\n\n

In this tutorial, we\u2019ll localize a CakePHP TO-DO app with English strings hardcoded in its templates and controllers. We\u2019ll mark those strings for translation, extract them into a catalog, translate the catalog into French in POEditor, and load the translated files back into the app.<\/p>\n\n\n\n

What CakePHP already handles for you<\/h2>\n\n\n\n

CakePHP 5 includes its i18n package and uses PHP\u2019s intl<\/code> extension for locale-aware formatting. Cake\\I18n\\Number<\/code> and Cake\\I18n\\DateTime<\/code> format a value according to whichever locale is active, and the framework\u2019s own strings live in a message domain called cake, whose translations are published separately, in the cakephp\/localized plugin.<\/p>\n\n\n\n

CakePHP cannot know which strings in your application should be translated. The TO-DO app we\u2019re starting from has username and password registration, a dashboard listing the account\u2019s to-do lists, and a page per list where tasks are added, edited, filtered and ticked off. Every one of its strings is an English literal sitting in a template or a controller.<\/p>\n\n\n\n

\"\"
The TO-DO app before translation, with its text hardcoded in English<\/em><\/figcaption><\/figure>\n\n\n\n

The screenshot has a second problem too. The line reading 5 tasks<\/code> left comes from a hand-written if <\/code>that picks between task and tasks, and the dates use format('n\/j\/Y g:i A')<\/code>, the American convention hardcoded into the template. Neither becomes correct for a French reader just because the words around them have been translated.<\/p>\n\n\n\n

To follow along you need PHP 8.2 or newer with the intl<\/code> extension enabled, since current CakePHP 5 releases require both, and a CakePHP application you can edit. Install the dependencies with composer install<\/code>, start the application with bin\/cake server<\/code>, and open the address it prints.<\/p>\n\n\n\n

Setting the default locale<\/h2>\n\n\n\n

The locale CakePHP falls back on lives in config\/app.php<\/code> under App.defaultLocale, and a stock application reads it from the environment so you can override it per deployment.<\/p>\n\n\n\n

\/\/ config\/app.php<\/em>
'App' => [
    'defaultLocale' => env('APP_DEFAULT_LOCALE', 'en_US'),
    \/\/ ...<\/em>
],<\/code><\/pre>\n\n\n\n
That one value decides more than which translations are loaded. It also sets the default formats used by Cake\\I18n\\Number<\/code> and Cake\\I18n\\DateTime<\/code>, so changing it moves dates and percentages to French conventions without any translated text being involved.<\/p>\n\n\n\n
Locale codes follow the ICU convention of a language and an optional region, written as en_US<\/code>, fr_FR<\/code> or fr_CA<\/code>. A bare fr<\/code> is valid too, and it is what this tutorial uses, because one catalog then serves every French-speaking region. Name the region only when you will ship a catalog that differs by region, such as a fr_CA<\/code> written for Canada.<\/p>\n\n\n\n
Record the languages the app ships in while you are here, because both the middleware and the language switcher need that list.<\/p>\n\n\n\n
\/\/ config\/app.php<\/em>
'I18n' => [
    'locales' => [
        'en_US' => 'English',
        'fr' => 'Fran\u00e7ais',
    ],
],<\/code><\/pre>\n\n\n\n
The __() function family<\/h2>\n\n\n\n
CakePHP exposes its translation functions globally, so they are available in controllers, templates, table classes and anywhere else without an import. There are eight, built from three ideas that combine in a fixed order.<\/p>\n\n\n\n
Function<\/th>What it adds<\/th><\/tr><\/thead>
__()<\/td>Translate a string<\/td><\/tr>
__d()<\/td>\u2026from a specific d<\/strong>omain<\/td><\/tr>
__n()<\/td>\u2026choosing between singular and plural by a n<\/strong>umber<\/td><\/tr>
__x()<\/td>\u2026with a contex<\/strong>t that disambiguates identical strings<\/td><\/tr>
__dn()<\/td>Domain and plural<\/td><\/tr>
__dx()<\/td>Domain and context<\/td><\/tr>
__xn()<\/td>Context and plural<\/td><\/tr>
__dxn()<\/td>Domain, context and plural<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
Read the names as d<\/code> for domain, x<\/code> for context and n<\/code> for plural. Most of your time goes in __()<\/code> and __n()<\/code>, and each of them returns its source string unchanged when no translation exists, so marking every string in one pass is safe and a string added after the last translation round still renders in English.<\/p>\n\n\n\n
Translating templates<\/h2>\n\n\n\n
Start with the layout, because it wraps every page. In the TO-DO app that is templates\/layout\/default.php<\/code>, where the brand, the navigation buttons and the signed-in line all need wrapping.<\/p>\n\n\n\n
<?php<\/strong> \/\/ templates\/layout\/default.php<\/em> ?><\/strong>
<a class<\/strong>=\"navbar-brand fw-semibold\" href=\"<?= $this->Url->build('\/') ?>\"><?= h(__('TO-DO app')) ?><\/strong><\/a>

<span class<\/strong>=\"text-body-secondary small\">
    <?= h(__('Signed in as {0}', $identity->get('username'))) ?><\/strong>
<\/span>

<?= $this->Form->postLink(
    __('Log out'),
    ['controller' => 'Users', 'action' => 'logout'],
    ['class' => 'btn btn-sm btn-outline-secondary'],
) ?><\/strong><\/code><\/pre>\n\n\n\n
Translate first and escape the result, never the other way round, because escaping first would hand the translator a string full of HTML entities. Helpers such as Form<\/code> and Html<\/code> take their labels as ordinary arguments, so a label gets wrapped in __()<\/code> like any other string.<\/p>\n\n\n\n
The page templates follow the same pattern, and the strings that get overlooked are the ones that are not body text: placeholders, aria-label<\/code> and title<\/code> attributes, and the confirmation text on a delete button.<\/p>\n\n\n\n
<?php<\/strong> \/\/ templates\/TodoLists\/index.php<\/em> ?><\/strong>
<?<\/strong>= $this->Form->control('name', [
    'label' => __('New list'),
    'placeholder' => __('Groceries'),
]) ?><\/strong>

<?<\/strong>= $this->Form->button(__('Create list'), ['class' => 'btn btn-primary w-100']) ?><\/strong>

<p class<\/strong>=\"text-body-secondary\"><?= h(__('No lists yet. Create your first one above.')) ?><\/strong><\/p><\/code><\/pre>\n\n\n\n
One string stays unmarked. The username field\u2019s placeholder reads demo<\/code> because that is the account name this walkthrough asks you to type, and a value that is data rather than prose is better left out of the catalog.<\/p>\n\n\n\n
Translating controllers and flash messages<\/h2>\n\n\n\n
Controllers hold the messages a user sees after doing something, and in the TO-DO app those were built by concatenation.<\/p>\n\n\n\n
\/\/ src\/Controller\/TodoListsController.php<\/em>
$this->Flash->success('List \"' . $todoList->name . '\" created.');<\/code><\/pre>\n\n\n\n
A concatenated message is difficult to translate because the translator does not get the complete sentence. They see List \"<\/code>, followed by the list name, and then \" created<\/code>. This also prevents them from changing the word order when the target language requires a different sentence structure. Make the whole message one string and pass the variable as a placeholder. <\/p>\n\n\n\n
\/\/ src\/Controller\/TodoListsController.php<\/em>
$this->Flash->success(__('List \"{0}\" created.', $todoList->name));<\/code><\/pre>\n\n\n\n
The {0}<\/code> is ICU MessageFormat, CakePHP\u2019s default way of interpolating arguments. The numbering allows the translator to change the word order. For example, a French translation can move {0}<\/code> to a different position in the sentence. Messages with two values use {0}<\/code> and {1}<\/code> as their placeholders. <\/p>\n\n\n\n
Page titles and anything else the controller sets get the same treatment.<\/p>\n\n\n\n
\/\/ src\/Controller\/TodoListsController.php<\/em>
$this->set('title', __('Your lists'));

$filters = [
    ['key' => 'all', 'label' => __('All'), 'count' => $totalCount],
    ['key' => 'open', 'label' => __('Open'), 'count' => $openCount],
    ['key' => 'done', 'label' => __('Done'), 'count' => $doneCount],
];<\/code><\/pre>\n\n\n\n
Translating validation messages and message domains<\/h2>\n\n\n\n
Validation messages in CakePHP live in table classes rather than templates, which makes them easy to forget until a French user submits an empty form and gets an English complaint back. In the TO-DO app they sit in validationDefault()<\/code> and buildRules()<\/code>.<\/p>\n\n\n\n
This is also where we can introduce a domain<\/strong>, which is a separate catalog file. Everything marked with plain __()<\/code> goes into a domain called default, and __d()<\/code> sends a message somewhere else.<\/p>\n\n\n\n
\/\/ src\/Model\/Table\/UsersTable.php<\/em>
$validator
    ->scalar('username')
    ->requirePresence('username', 'create')
    ->notEmptyString('username', __d('validation', 'Pick a username.'))
    ->lengthBetween('username', [3, 80], __d('validation', 'Usernames are 3 to 80 characters long.'));

$rules->add(
    $rules->isUnique(['username'], __d('validation', 'That username is taken.')),
    ['errorField' => 'username'],
);<\/code><\/pre>\n\n\n\n
CakePHP also uses some predefined domains: the framework\u2019s own strings are in cake, and each plugin gets a domain named after it. Your own messages are the only ones that need marking.<\/p>\n\n\n\n
Keeping form errors apart from interface labels gives a translator a coherent batch of similar strings to work through, at the cost of a second file to import and keep in sync.<\/p>\n\n\n\n
Plurals: __n() or ICU MessageFormat<\/h2>\n\n\n\n
The TO-DO app picks its singular and plural forms by hand in four places, and the dashboard is the clearest of them.<\/p>\n\n\n\n
\/\/ src\/Controller\/TodoListsController.php<\/em>
if<\/strong> ($listCount === 1) {
    $listCountLabel = $listCount . ' list';
} else<\/strong> {
    $listCountLabel = number_format($listCount) . ' lists';
}<\/code><\/pre>\n\n\n\n
This assumes that every language has two plural forms and that the singular is used only for one item. That is not true for all languages. Polish has four plural forms, Arabic has six, and French uses the singular form for zero. <\/p>\n\n\n\n
CakePHP gives you two ways out.<\/p>\n\n\n\n
__n()<\/code><\/strong> takes a singular message, a plural message and the count<\/strong>. The catalog then stores the plural forms required by the target language. <\/p>\n\n\n\n
\/\/ src\/Controller\/TodoListsController.php<\/em>
$listCountLabel = __n(
    'You have {0} list.',
    'You have {0} lists.',
    $listCount,
    Number::format($listCount),
);<\/code><\/pre>\n\n\n\n
ICU plural syntax puts every form inside a single message<\/strong>, which one translator then fills in as one string.<\/p>\n\n\n\n
$listCountLabel = __('{0,plural,=0{You have no lists.} one{You have one list.} other{You have # lists.}}', $listCount);<\/code><\/pre>\n\n\n\n
For this tutorial we\u2019ll use __n()<\/code> throughout: it is what bin\/cake i18n extract<\/code> writes into the catalog natively, and it is what POEditor\u2019s plural editor is built around. We recommend keeping plural forms separate rather than using ICU MessageFormat, since separate forms are easier to work with in the translation workflow. Replace the other three manual plural branches in the same way. <\/p>\n\n\n\n
Extracting the strings with bin\/cake i18n extract<\/h2>\n\n\n\n
With the strings marked, CakePHP\u2019s console command scans the code and writes a .pot<\/code> file, which is the template catalog a translator works from.<\/p>\n\n\n\n
bin\/cake i18n extract --paths src,templates --output resources\/locales --extract-core no --overwrite<\/code><\/pre>\n\n\n\n
Run bare, the command prompts for each of those values. --extract-core<\/code> no leaves CakePHP\u2019s own strings out, --overwrite<\/code> replaces the previous template instead of asking, and pointing --paths<\/code> at src<\/code> and templates<\/code> avoids the reflection warnings that config produces for its migration and seed classes.<\/p>\n\n\n\n
The output lands in resources\/locales\/<\/code>, one file per domain, so our split produces two.<\/p>\n\n\n\n
resources\/locales\/
\u251c\u2500\u2500 default.pot
\u2514\u2500\u2500 validation.pot<\/code><\/pre>\n\n\n\n
Open default.pot<\/code> to see the structure of the extracted catalog. <\/p>\n\n\n\n
# resources\/locales\/default.pot
#: .\/src\/Controller\/TodoListsController.php:31
msgid \"You have {0} list.\"
msgid_plural \"You have {0} lists.\"
msgstr[0] \"\"
msgstr[1] \"\"

#: .\/src\/Controller\/TodoListsController.php:98
#: .\/templates\/TodoLists\/index.php:42
msgid \"{0} task left\"
msgid_plural \"{0} tasks left\"
msgstr[0] \"\"
msgstr[1] \"\"<\/code><\/pre>\n\n\n\n
The #:<\/code> lines are source references, and the second entry carries two of them: the list page and the dashboard word their count the same way, so four call sites collapsed into three entries. Putting the whole sentence inside the message is what let them match. The msgstr<\/code> values are empty because a .pot<\/code> is a template: it holds the source messages and nothing else.<\/p>\n\n\n\n
Extraction reads literals, so a string built at runtime and passed to __()<\/code> as a variable never reaches your translator.<\/p>\n\n\n\n
Translating the catalog in POEditor<\/h2>\n\n\n\n
Editing a .pot<\/code> file by hand becomes difficult as the number of strings grows, especially when translators or other non-developers need to work on the project. POEditor<\/a> gives the catalog a web interface, keeps a translation memory across your projects on paid plans, and hands back a .po<\/code> file in the same format CakePHP already reads.<\/p>\n\n\n\n
Start by creating a project for the application.<\/p>\n\n\n\n
\"\"
The project created for the TO-DO app<\/em><\/figcaption><\/figure>\n\n\n\n
Then add the languages the app ships in: English as the source and French as the target.<\/p>\n\n\n\n
\"\"
English and French added to the project, both still empty<\/em><\/figcaption><\/figure>\n\n\n\n
Import default.pot<\/code> on the import page with Add tags<\/strong> switched on and the tag set to default<\/code>, then validation.pot<\/code> with the tag set to validation<\/code>.<\/p>\n\n\n\n
\"\"
Importing<\/em> default.pot, tagging every term it creates<\/em><\/figcaption><\/figure>\n\n\n\n
Both files land in the same project, and those tags are what let one project produce two separate catalogs again on the way out. Two strings appear in both files, and POEditor stores them once with both tags. For that to work, tag all the terms in validation.pot on the second import, not only the new ones, so the shared strings pick up the validation tag as well.<\/p>\n\n\n\n
\"\"
Each term tagged with the domain it was imported from<\/em><\/figcaption><\/figure>\n\n\n\n
Importing a .pot creates the terms, but the file does not contain translations. As a result, the English language shows 0% translated in POEditor. Use Copy Terms to Translations<\/strong> to copy the English terms into the English translations so they can be used as a reference while translating into French. <\/p>\n\n\n\n
\"\"
Copy Terms to Translations, on the English language<\/em><\/figcaption><\/figure>\n\n\n\n
Now translate. The terms carrying {0}<\/code> and {1}<\/code> need their placeholders kept intact, though they can be moved wherever French word order wants them. If a translation leaves one out, POEditor shows a warning under the translation box.<\/p>\n\n\n\n
If you would rather review a first draft than translate from scratch, you can pre-fill the French strings with Automatic Translation (Google Translate, DeepL or Azure AI Translator), which is built in, or with AI translation from providers such as OpenAI or Anthropic\u2019s Claude once you add your own API key.<\/p>\n\n\n\n
\"\"
Working through the French translations with the English reference alongside<\/em><\/figcaption><\/figure>\n\n\n\n
The plural terms offer a field per form, and French needs three where English needs two: the catalog carries as many forms as the target language has, not as many as the source.<\/p>\n\n\n\n
\"\"
A plural term with a field for each of the forms French needs<\/em><\/figcaption><\/figure>\n\n\n\n
When the translations are done, export French as a .po<\/code> file, once per domain. Filter the export by the default<\/code> tag for the first file and the validation<\/code> tag for the second, because an export with an empty tag filter returns every term in the project and would collapse your two domains back into one.<\/p>\n\n\n\n
\"\"
Exporting the French catalog, filtered to the<\/em> default<\/em> tag<\/em><\/figcaption><\/figure>\n\n\n\n
Loading the French catalog and switching language<\/h2>\n\n\n\n
CakePHP looks for catalogs under resources\/locales\/<\/code>, in a folder named after the locale, with one file per domain. Copy the exported files into that directory.<\/p>\n\n\n\n
resources\/locales\/
\u251c\u2500\u2500 default.pot
\u251c\u2500\u2500 validation.pot
\u2514\u2500\u2500 fr\/
    \u251c\u2500\u2500 default.po
    \u2514\u2500\u2500 validation.po<\/code><\/pre>\n\n\n\n
There is no compile step<\/h3>\n\n\n\n
If you have localized a Django or a plain gettext project, this is where you would reach for msgfmt<\/code> or compilemessages<\/code> to turn the .po<\/code> into a binary .mo<\/code>. CakePHP does not need it: its message loader defaults to the .po<\/code> extension and parses the file directly, so the file POEditor exports is the file the application runs on. Translations are cached aggressively, though, so clear the cache after dropping in a new catalog.<\/p>\n\n\n\n
bin\/cake cache clear_all<\/code><\/pre>\n\n\n\n
Folder naming follows a fallback, and its order is worth knowing: for an fr_FR<\/code> locale CakePHP looks in resources\/locales\/fr\/<\/code> before resources\/locales\/fr_FR\/<\/code> and loads the first catalog it finds. A single fr<\/code> folder therefore covers every French-speaking region, which is why this tutorial uses one, and a fr_FR<\/code> folder is only read when fr<\/code> has no file for that domain.<\/p>\n\n\n\n
Switching at runtime<\/h3>\n\n\n\n
I18n::setLocale()<\/code> sets the locale for the current request. To pick one up from the browser, CakePHP ships LocaleSelectorMiddleware<\/code>, which reads the Accept-Language<\/code> header and matches it against the locales you allow.<\/p>\n\n\n\n
\/\/ src\/Application.php<\/em>
use<\/strong> Cake\\I18n\\Middleware\\LocaleSelectorMiddleware;

$middlewareQueue
    ->add(new<\/strong> LocaleSelectorMiddleware(
        array_keys((array)Configure::read('I18n.locales')),
    ));<\/code><\/pre>\n\n\n\n
Passing that list matters. With no list, the middleware never sets a locale at all, and with ['*']<\/code> it accepts any header, including languages you have no catalog for. Restricting it to the two languages the app ships means an unrecognised header falls back to App.defaultLocale<\/code>.<\/p>\n\n\n\n
Keying that list on fr<\/code> rather than fr_FR<\/code> is what makes it work for every French reader. Locale::lookup()<\/code> shortens a requested tag but never lengthens it, so fr matches a browser asking for fr<\/code>, fr-FR<\/code> or fr-CA<\/code> alike, while fr_FR<\/code> would match only French (France) and send every other French reader to English.<\/p>\n\n\n\n
The Accept-Language<\/code> header is only used as the initial locale selection. To let users choose a language manually, the switcher sends the selection to a controller action, which stores it in the session. <\/p>\n\n\n\n
\/\/ src\/Controller\/LocaleController.php<\/em>
public<\/strong> function<\/strong> change(string $locale): ?Response
{
    $this->request->allowMethod(['post']);

    if<\/strong> (!array_key_exists($locale, $this->availableLocales())) {
        throw<\/strong> new<\/strong> NotFoundException(__('That language is not available.'));
    }

    $this->request->getSession()->write(self<\/strong>::LOCALE_SESSION_KEY, $locale);
    I18n::setLocale($locale);

    return<\/strong> $this->redirect($this->localRedirectTarget());
}<\/code><\/pre>\n\n\n\n
Do not name that action set(): Controller::set()<\/code> already exists for passing variables to the view, so an action of that name dies with a signature clash before the page renders.<\/p>\n\n\n\n
Read the stored locale in AppController::beforeFilter()<\/code>. This runs after the middleware, so the session value can override the locale selected from the Accept-Language<\/code> header. <\/p>\n\n\n\n
\/\/ src\/Controller\/AppController.php<\/em>
public<\/strong> function<\/strong> beforeFilter(EventInterface $event): void
{
    parent<\/strong>::beforeFilter($event);

    $locale = $this->request->getSession()->read(self<\/strong>::LOCALE_SESSION_KEY);

    if<\/strong> ($locale && array_key_exists($locale, $this->availableLocales())) {
        I18n::setLocale($locale);
    }
}<\/code><\/pre>\n\n\n\n
Watch the case.<\/strong> LocaleSelectorMiddleware<\/code> resolves the header by calling Locale::lookup()<\/code> with canonicalization on, which returns a lower-cased tag, so a region-coded entry comes back changed: a browser asking for en-US leaves I18n::getLocale()<\/code> reading en_us<\/code>. The translations still load, but a ===<\/code> comparison against your configured keys fails and the switcher shows no language as active. Compare with strcasecmp()<\/code>.<\/p>\n\n\n\n
With the catalog in place and the switcher wired up, the app reads in French, and the count reads Il reste 5 t\u00e2ches<\/code> because __n()<\/code> is choosing the form from the catalog rather than the hand-written if<\/code> we deleted.<\/p>\n\n\n\n
\"\"
The same list page after switching to French, with the switcher in the navbar<\/em><\/figcaption><\/figure>\n\n\n\n
The messages from the validation<\/code> domain arrive with the rest, so a form submitted with a too-short username answers in French as well.<\/p>\n\n\n\n
\"\"
A validation message from the<\/em> validation<\/em> domain, in French<\/em><\/figcaption><\/figure>\n\n\n\n
Dates, numbers and percentages<\/h2>\n\n\n\n
A French reader also expects 16 sept. 2026<\/code> rather than Sep 16, 2026<\/code>, a comma where English puts a decimal point, and a space before a percent sign. The TO-DO app currently uses US-style formats in its templates. <\/p>\n\n\n\n
\/\/ templates\/TodoLists\/index.php<\/em>
created <?= h($list->created->format('n\/j\/Y')) ?><\/strong><\/code><\/pre>\n\n\n\n
Cake\\I18n\\DateTime<\/code> reads the active locale, so switching to i18nFormat()<\/code> or nice()<\/code> gets the formatting for free.<\/p>\n\n\n\n
<?php<\/strong> \/\/ templates\/TodoLists\/index.php<\/em> ?><\/strong>
<?<\/strong>= h(__('created {0}', $list->created->i18nFormat([\\IntlDateFormatter::MEDIUM, \\IntlDateFormatter::NONE]))) ?><\/strong><\/code><\/pre>\n\n\n\n
Numbers work the same way through Cake\\I18n\\Number<\/code>, and the progress line mixes a formatted percentage into a translatable sentence.<\/p>\n\n\n\n
\/\/ src\/Controller\/TodoListsController.php<\/em>
$progressLabel = __(
    '{0} of {1} tasks done',
    Number::toPercentage($todoList->percent_done, 1),
    Number::format($totalCount),
);<\/code><\/pre>\n\n\n\n
In English that renders as 0.0% of 5 tasks done<\/code>, and once the sentence itself is translated, as 0,0 % des 5 t\u00e2ches faites<\/code> in French, with the comma and the space before the percent sign applied by ICU rather than by anything in your code. The dates move the same way, and the timestamps drop AM\/PM for a 24-hour clock.<\/p>\n\n\n\n
\"\"
French dates on the dashboard, with both plural forms of the task count<\/em><\/figcaption><\/figure>\n\n\n\n
The locale does not carry the time zone. I18n::setLocale()<\/code> changes how a time is written, not which moment it refers to, so an application with users in several countries still needs to set a time zone per user and convert before formatting.<\/p>\n\n\n\n
Translating content in the database<\/h2>\n\n\n\n
Everything so far has been static text in your source code, and a .po<\/code> file is the right home for it. Content users create is a different problem: the TO-DO app\u2019s lists and tasks are typed by the account that owns them, so there is nothing to translate.<\/p>\n\n\n\n
Editorial content is where this changes. Category names, a product catalogue or help text stored in a table are written by you, shown to everyone, and need a version per language. CakePHP handles them with the Translate behavior, attached to a table rather than threaded through your queries.<\/p>\n\n\n\n
\/\/ src\/Model\/Table\/CategoriesTable.php<\/em>
$this->addBehavior('Translate', ['fields' => ['name', 'description']]);<\/code><\/pre>\n\n\n\n
A find then returns the translation for whichever locale is active, and writing one means setting _locale<\/code> on the entity before saving. By default the translations live in a companion categories_translations<\/code> table, and the Translate behavior docs<\/a> cover the shared-table alternative. Use it for content managed by your application rather than content entered by individual users.<\/p>\n\n\n\n
Keeping the catalogs in sync<\/h2>\n\n\n\n
The catalogs need to be updated when the application changes. You can use the same extraction command to generate an updated .pot<\/code> file. <\/p>\n\n\n\n
bin\/cake i18n extract --paths src,templates --output resources\/locales --extract-core no --overwrite<\/code><\/pre>\n\n\n\n
Re-running it picks up new strings and drops the ones you have deleted. Import the refreshed .pot<\/code> into POEditor and the new terms appear untranslated while the existing ones keep their translations, so a translator only sees what changed. Terms you removed from the code stay in the POEditor project until you delete them, though. Tagging the obsolete terms on import makes them easy to find.<\/p>\n\n\n\n
A message is identified by its text, so changing Give the list a name<\/code>. to Please give the list a name. does not edit a term, it creates a new one and orphans the old. Every translation reverts to untranslated, which is correct behaviour for a changed sentence, but it means a wording tweak on release day puts every language back into the queue.<\/p>\n\n\n\n
If you update the catalogs regularly, consider automating this process. POEditor has an API<\/a> and integrations that let you push a .pot<\/code> and pull finished .po<\/code> files as part of a build, so the catalogs follow the code rather than trailing a release behind it.<\/p>\n\n\n\n
A simpler safety net is to run the extract command in CI and fail the build when the committed .pot files are out of date. Every run rewrites the POT-Creation-Date header and the #: line references shift whenever code moves, so tell the diff to ignore those lines, for example with git diff –exit-code -I ‘^#:’ -I ‘^”POT-Creation-Date’ resources\/locales. That catches a marked string nobody extracted before it ships untranslated. Note that git diff only compares files the repository already tracks, so commit a new domain\u2019s .pot the first time it appears, or the check will never see it.<\/p>\n\n\n\n
Wrapping up<\/h2>\n\n\n\n
The TO-DO app now marks its strings with __()<\/code> and __n()<\/code>, keeps its validation messages in their own domain, extracts to a .pot<\/code> with a single console command, takes its French from a real translation workflow rather than a hand-edited file, and switches between English and French from the navbar. Because CakePHP reads .po<\/code> files directly, shipping a new language means adding a folder and clearing a cache, with no compile step anywhere in the deploy.<\/p>\n\n\n\n
Create a free POEditor account<\/a> and import your .pot<\/code> file to see how your own catalog looks with a translation interface around it.<\/p>\n\n\n\n
If you are localizing something else in the same stack, these guides cover the same ground for other frameworks:<\/p>\n\n\n\n