Extracting & Loading Strings

Using the Console Command To Extract Messages

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.

Tip

See TMS Support for translation management systems we support out-of-the-box.

./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.

Tip

If you wish to use a different function name (e.g., maybe you wish to wrap this method call in a Closure, etc.), you may do so, but you must provide the --additional-function-names option to the formatphp extract console command. This option takes a comma-separated list of function names for the extractor to parse.

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

To see all available options, view the command help with formatphp help extract.

Using MessageLoader to Load Messages

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.

Testing With Pseudo Locales

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.

Pseudo locales

Locale	Message
en-XA	ṁẏ ńâṁè íś {name}
en-XB	[!! ṁẏ ńâṁṁṁè íííś  !!]{name}
xx-AC	MY NAME IS {name}
xx-HA	[javascript]my name is {name}
xx-LS	my name is {name}SSSSSSSSSSSSSSSSSSSSSSSSS

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 configure and load the pseudo locale just like with other locales.

Tip

To see all available options, view the command help with formatphp help pseudo-locale.