wikimedia/mediawiki-extensions-Translate

<?php
declare( strict_types = 1 );

namespace MediaWiki\Extension\Translate\FileFormatSupport;

use FileBasedMessageGroup;
use MediaWiki\Extension\Translate\MessageLoading\MessageCollection;

/**
 * Interface for file format support classes. These classes handle parsing and generating
 * various different file formats where translation messages are stored.
 *
 * @ingroup FileFormatSupport
 * @defgroup FileFormatSupport File format support
 * @author Niklas Laxström
 * @copyright Copyright © 2008-2013, Niklas Laxström
 * @license GPL-2.0-or-later
 */
interface FileFormatSupport {
    public function __construct( FileBasedMessageGroup $group );

    /**
     * Set the file's location in the system
     * @param string $target Filesystem path for exported files.
     */
    public function setWritePath( string $target );

    /** Get the file's location in the system */
    public function getWritePath(): string;

    /**
     * Will parse messages, authors, and any custom data from the file
     * and return it in associative array with keys like \c AUTHORS and
     * \c MESSAGES.
     * @param string $code Language code.
     * @return array|bool Parsed data or false on failure.
     */
    public function read( string $code );

    /**
     * Same as read(), but takes the data as a parameter. The caller
     * is supposed to know in what language the translations are.
     * @param string $data Formatted messages.
     * @return array Parsed data.
     */
    public function readFromVariable( string $data ): array;

    /**
     * Writes to the location provided with setWritePath and group specific
     * directory structure. Exports translations included in the given
     * collection with any special handling needed.
     */
    public function write( MessageCollection $collection );

    /**
     * Quick shortcut for getting the plain exported data.
     * Same as write(), but returns the output instead of writing it into
     * a file.
     */
    public function writeIntoVariable( MessageCollection $collection ): string;

    /**
     * Query the capabilities of this FFS. Allowed values are:
     *  - yes
     *  - write (ignored on read)
     *  - no (stripped on write)
     */
    public function supportsFuzzy(): string;

    /**
     * Checks whether two strings are equal. Sometimes same content might
     * have multiple representations. The main case are inline plurals,
     * which in some formats require expansion at export time.
     */
    public function isContentEqual( ?string $a, ?string $b ): bool;

    /**
     * Return the commonly used file extensions for these formats. Include the dot.
     * @return string[]
     */
    public function getFileExtensions(): array;

    /**
     * Allows to skip writing the export output into a file. This is useful
     * to skip updates that would only update irrelevant parts, such as the
     * timestamp of the export.
     *
     * @param string $a The existing content.
     * @param string $b The new export content.
     */
    public function shouldOverwrite( string $a, string $b ): bool;
}