The formatphp extract console command helps you extract messages from your application source code, saving them to JSON files that your translation management system can use.

./vendor/bin/formatphp extract \
    --out-file=locales/en.json \
    'src/**/*.php' \
    'src/**/*.phtml'

In order for message extraction to function properly, we have a few rules that must be followed (see comments inline in the following example):

// The method name must be exactly `formatMessage` (see Tip below).
// The name of the variable (i.e., `$formatphp`) does not matter.
$formatphp->formatMessage(

    // The message descriptor must be an array literal.
    [
        'id' => 'hello', // ID (if provided) must be a string literal.
        'description' => 'Message to translators', // Description must be a string literal.
        'defaultMessage' => 'My name is {name}', // Message must be a string literal.
    ],

    [
        'name' => $userName,
    ],

);

At least one of id or defaultMessage must be present.

--additional-function-names='formatMessage, myCustomFormattingFunction'

We provide a message loader to load translation strings from locale files that have been generated by your translation management system.

use FormatPHP\Config;
use FormatPHP\FormatPHP;
use FormatPHP\Intl;
use FormatPHP\MessageLoader;

$config = new Config(new Intl\Locale('es-419'));

$messageLoader = new MessageLoader(

    // The path to your locale JSON files (i.e., en.json, es.json, etc.).
    '/path/to/app/locales',

    // The configuration object created above.
    $config,

);

$formatphp = new FormatPHP($config, $messageLoader->loadMessages());

This example assumes a directory of locale JSON files located at /path/to/app/locales, which includes an en.json file with these contents:

{
  "hello": {
    "defaultMessage": "Hello, {name}! Today is {today}."
  }
}

and an es.json file with these contents:

{
  "hello": {
    "defaultMessage": "¡Hola {name}! Hoy es {today}."
  }
}

The message loader uses a fallback method to choose locales. In this example, if the configured locale is es-419 (i.e., Spanish appropriate for the Latin America and Caribbean region), the fallback method will choose es.json for the messages.

Pseudo locales provide a way to test an application with various types of characters and string widths. FormatPHP provides a tool to convert any locale file to a pseudo locale for testing purposes.

Given the English message my name is {name}, the following table shows how each supported pseudo locale will render this message.

To convert a locale to a pseudo locale, use the formatphp pseudo-locale console command.

./vendor/bin/formatphp pseudo-locale \
    --out-file locales/en-XA.json \
    locales/en.json \
    en-XA

You may then :ref:`configure and load <string-extraction.messageloader>` the pseudo locale just like with other locales.