CakePHP Translation: Agile Localization for Devs

CakePHP is a web framework for PHP which uses commonly known design patterns. It is generally used for handling web applications, the huge library support in CakePHP makes the development clear and easy.

In this article, you will discover CakePHP translation basics, how to keep the localization process agile and easily manage the translation of constant app updates.

Automate Localization With VCS Integrations

Localization is an essential step to opening your product to a global market. To reap the benefits and enjoy both the result and the process, the localization process needs to be organized in an agile way.

The best way to integrate the localization process into your development workflow is to use a localization management platform that integrates with your software repository.

Integration with your repository ensures that the new texts from the selected branches are sent to your localization project right away, and all the translations are automatically added to your repo as a pull request.

Make all of these steps automated to save your time for other tasks. On Crowdin, you can connect your localization projects with GitHub, GitLab, Bitbucket, Azure Repos, or install Crowdin Console Client (CLI) that allows you to integrate with GIT, SVN, Mercurial, and more.

CakePHP Localization Basics

Translated copy isn’t the only point to include in an application that is intended for a multilingual market. You should also consider date and time formats, currency symbols, and pluralization.

To make it easier for you to understand the basics, let’s talk about CakePHP localization and gettext.

CakePHP – Gettext

Since CakePHP follows standard gettext strategies, CakePHP localization requires storing translatable text in .po files. It is one of the most common human/machine-readable file formats.

So that’s why the first step towards the multilingual CakePHP app is to install gettext.

Set Up CakePHP Translations

The easiest way to go from a single-language application to a multilingual application is to use the __() function in your code.

Below is an example of some code for a single-language application:

<h2>Home page</h2>

To internationalize your code, all you need to do is to wrap all strings you need to localize in __() like so:

<h2><?= __('Home page') ?></h2>

These two code examples are identical in terms of functionality – they will both send the content to the browser. The __() function will translate the passed string if a translation is available or return it without any changes. Hence, the original string will appear on the web page.

Note: You do not need to instantiate the L10n class at all. It happens automatically the first time the __() function is called.

Create Language Files

You need to create one or more .po files, depending on how massive the file is and how many languages you want. Place files under src/Locale/ and within this directory. Remember to create a subfolder for each language the application needs to support.

If you choose to use just one .po file, you’ll wrap your strings with the __() helper. If you choose to have multiple .po files in order to avoid one massive file, you can use the __d() helper so that you could specify the domain (domain = name of the .po file without the .po extension).

Translation folders can be the two or three-letter ISO code of the language or the full locale name such as fr_FR, es_ES, es_DO, which contains both the language and the country where it is spoken.

View Crowdin languages codes.

/src
        /Locale
            /fr
                mywebapp.po
            /es
                mywebapp.po

The source strings will be marked with “msgid” and shouldn’t be changed. Strings marked with “msgstr” are where you put the translation. The translation starts blank and needs to be filled in. Don’t forget to keep quotes around your translation.

If “msgctxt” is given, it will be used as part of the translation title, which you can use to provide the context. In the next section, we will cover more details about context.

An example translation file:

msgid "Settings and privacy"
msgstr "Paramètres et confidentialité"

Once you install the integration with your VSC system, you can customize content synchronization between your repository and Crowdin. For this, change the configuration in the Crowdin UI, or edit the configuration file based on your preferences and upload it.

For example, you can define the path for files, map your own languages to be recognizable in your localization projects, rename translation files, select files and directories that you don’t need to translate, and more.

Read more about VCS Integrations and a configuration file.

Add String Context

Providing translators with context improves translation quality, makes the translation process easier, and streamlines the QA process by reducing the possibility of user error.

You can add a “comment” to your string to give translators hints about a translatable string.

For example, the word “email” in English refers to a noun and a verb. To specify which one is used here, you can use the __x() function. The context will appear on the msgctxt line in the resulting .po file.

echo __x('noun', 'email');

echo __x('verb', 'email');

The first argument is the context of the message, and the second is the message to be translated.

msgctxt "noun"
msgid "email"
msgstr ""

Set the Default Locale

Set the default locale in your config/app.php file by setting App.defaultLocale. The default locale controls several aspects of your application, including the default language, the date and time formats. It can also control the number or currency format whenever any of those is displayed using CakePHP’s localization libraries.

'App' => [
    ...
    'defaultLocale' => env('APP_DEFAULT_LOCALE', 'en_US'),
    ...
]

Check out the official CakePHP documentation to discover further information about using plurals, variables, and more.

Provide Context – Improve the Translation Quality

Context makes the translation process easier for translators and ensures the quality of your localized product. There are numerous ways to provide context. It can be screenshots, videos, a link to the entire file, or better – a visual preview right in the Editor where translators work, and more.

The original context is particularly important when sentences are short or consist of few words, as often happens in our case with web applications.

To make it easier for you to provide context for translators and reduce manual work, Crowdin has created an In-Context Localization tool.

The tool provides an overlay for your app. It allows translators to translate and receive context in real-time. In-context localization is connected with the actual project created in Crowdin, which contains the translatable files. Translators can work as if in the real app interface and preview the translations they make right there. Translation files are stored within your Crowdin project, and you can decide when to pull them to your application (for example, only pull them after review by a proofreader, so you can be confident in the quality of the final product).

Read our article to learn more about the In-Context tool and other ways to provide context for translators on Crowdin.