TMS Support

A translation management system, or TMS, allows translators to use your default locale file to create translations for all the other languages your application supports. To work with a TMS, you will extract the formatted strings from your application to send to the TMS. Often, a TMS will specify a particular document format they require.

To extract strings in a specific TMS format, use the --format option.

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

Out of the box, FormatPHP supports the following formatters for integration with third-party TMSes. Supporting a TMS does not imply endorsement of that particular TMS.

Table 2 Translation management systems
TMS	`--format=`
Crowdin Chrome JSON	`crowdin`
Lingohub	`simple`
locize	`simple`
Phrase	`simple`
SimpleLocalize	`simple`
Smartling ICU JSON	`smartling`

Our default formatter is formatphp, which mirrors the output of the default formatter for FormatJS.

Custom Formatters

You may provide your own formatter using our interfaces. You will need to create a writer for the format. Optionally, you may create a reader, if using our message loader or the formatphp pseudo-locale command with the --in-format option.

The writer must implement FormatPHP\Format\WriterInterface or be a callable of the shape:

callable(FormatPHP\DescriptorCollection, FormatPHP\Format\WriterOptions): mixed[]

The reader must implement FormatPHP\Format\ReaderInterface or be a callable of the shape:

callable(mixed[]): FormatPHP\MessageCollection

To use your custom writer with the formatphp extract CLI tool, pass the fully-qualified class name to --format, or a path to a script that returns the callable.

For example, given the script my-writer.php with the following contents:

<?php

use FormatPHP\DescriptorCollection;
use FormatPHP\Format\WriterOptions;

require_once 'vendor/autoload.php';

/**
 * @return mixed[]
 */
return function(DescriptorCollection $descriptors, WriterOptions $options): array {
    // Custom writer logic to create an array of data we will write
    // as JSON to a file, which your TMS will be able to use.
};

You may call formatphp extract like this:

./vendor/bin/formatphp extract \
    --format='path/to/my-writer.php' \
    --out-file=locales/en.json \
    'src/**/*.php'

Then, to use a custom reader with the message loader, you may do something like the following:

$messageLoader = new \FormatPHP\MessageLoader(

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

    // The configuration object created earlier.
    $config,

    // Pass your custom reader through the formatReader parameter.
    MyCustomReader::class,

);

The formatReader parameter of the MessageLoader constructor accepts the following:

Fully-qualified class name for a class that implements FormatPHP\Format\ReaderInterface
An already-instantiated instance object of FormatPHP\Format\ReaderInterface
A callable with the shape callable(mixed[]): FormatPHP\MessageCollection
The path to a script that returns a callable with this shape