1	<?php
2	declare( strict_types = 1 );
3
4	namespace MediaWiki\Extension\Translate\FileFormatSupport;
5
6	use FileBasedMessageGroup;
7	use MediaWiki\Extension\Translate\MessageLoading\MessageCollection;
8
9	/**
10	* Interface for file format support classes. These classes handle parsing and generating
11	* various different file formats where translation messages are stored.
12	*
13	* @ingroup FileFormatSupport
14	* @defgroup FileFormatSupport File format support
15	* @author Niklas Laxström
16	* @copyright Copyright © 2008-2013, Niklas Laxström
17	* @license GPL-2.0-or-later
18	*/
19	interface FileFormatSupport {
20	public function __construct( FileBasedMessageGroup $group );
21
22	/**
23	* Set the file's location in the system
24	* @param string $target Filesystem path for exported files.
25	*/
26	public function setWritePath( string $target );
27
28	/** Get the file's location in the system */
29	public function getWritePath(): string;
30
31	/**
32	* Will parse messages, authors, and any custom data from the file
33	* and return it in associative array with keys like \c AUTHORS and
34	* \c MESSAGES.
35	* @param string $code Language code.
36	* @return array|bool Parsed data or false on failure.
37	*/
38	public function read( string $code );
39
40	/**
41	* Same as read(), but takes the data as a parameter. The caller
42	* is supposed to know in what language the translations are.
43	* @param string $data Formatted messages.
44	* @return array Parsed data.
45	*/
46	public function readFromVariable( string $data ): array;
47
48	/**
49	* Writes to the location provided with setWritePath and group specific
50	* directory structure. Exports translations included in the given
51	* collection with any special handling needed.
52	*/
53	public function write( MessageCollection $collection );
54
55	/**
56	* Quick shortcut for getting the plain exported data.
57	* Same as write(), but returns the output instead of writing it into
58	* a file.
59	*/
60	public function writeIntoVariable( MessageCollection $collection ): string;
61
62	/**
63	* Query the capabilities of this FFS. Allowed values are:
64	*  - yes
65	*  - write (ignored on read)
66	*  - no (stripped on write)
67	*/
68	public function supportsFuzzy(): string;
69
70	/**
71	* Checks whether two strings are equal. Sometimes same content might
72	* have multiple representations. The main case are inline plurals,
73	* which in some formats require expansion at export time.
74	*/
75	public function isContentEqual( ?string $a, ?string $b ): bool;
76
77	/**
78	* Return the commonly used file extensions for these formats. Include the dot.
79	* @return string[]
80	*/
81	public function getFileExtensions(): array;
82
83	/**
84	* Allows to skip writing the export output into a file. This is useful
85	* to skip updates that would only update irrelevant parts, such as the
86	* timestamp of the export.
87	*
88	* @param string $a The existing content.
89	* @param string $b The new export content.
90	*/
91	public function shouldOverwrite( string $a, string $b ): bool;
92	}