CakePHP Translation: Agile Localization for Devs

CakePHP is an open-source web framework for PHP which uses commonly known design patterns. Based on model-view-controller, it is generally used for handling web applications, the informative CakePHP library makes the development clear.

Our article will teach you how CakePHP Translation basics can help you automate your localization and translate regular app updates with ease.

Automate Localization with VCS Integrations

Localization is an important step that opens your product to a global market. In order to reap the benefits of localization and enjoy both the result and process, it should be organized in a highly agile manner.

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

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.

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.

CakePHP Localization Basics

Developers often underestimate the complexity of localization. An application aiming for a multilingual market should contain more than just translated copy. 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 simplest way to “transform” a single-language application into a multilingual application is to use the __() function in your code.

Here 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. If there are no translations, it returns the texts without any changes. That means, the original string will appear on the web page.

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

Create Language Files

Create one or more .po files, depending on how the file is and how many languages you want. Place files under src/Locale/ and within this directory. It's important 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.

Let's look at the word "email". In English, it 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

You can 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 ensures the quality of your localized product and makes the translation process easier. There are a lot of ways to provide context. It can be screenshots, videos, a link to the entire file, or even better – a visual preview right in the Editor where translators work.

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.

You can use the tool to create an overlay for your app. Translators can translate and receive context in real-time. In-context localization is connected with the actual project created in Crowdin, which contains the translatable files. The translators can preview their translations as if in the real app interface. 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 reviewing by a proofreader, so you can be confident in the quality of the final product).

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

Localize Your App with Crowdin

Automate localization process, release your app in several languages simultaneously, and provide an enhanced experience for your global customers with Crowdin.

Get started and register a Crowdin account.