<?php
/**
 * Widget-chrome translations.
 *
 * @package Mapsemble
 */

namespace Mapsemble;

/**
 * Builds the translations table passed to the widget's init().
 *
 * The key set is shared with the Drupal module's MapsembleTranslations
 * byte for byte — the widget contract is one and the same. Keys whose
 * translation equals the source add nothing (the widget's built-in
 * defaults are exactly these English strings), so an untranslated site
 * ships no table at all.
 *
 * Dynamic strings from the Mapsemble map itself (Drupal's
 * "Refresh from remote" flow) have no WordPress port yet; the
 * `mapsemble_widget_translations` filter is the seam for them.
 */
class Translations {

	/**
	 * The built-in UI-chrome source strings, translated.
	 *
	 * Written out one literal at a time so `wp i18n make-pot` extracts
	 * them; do not fold into a loop over a constant.
	 *
	 * @return array<string, string> source => translated.
	 */
	public function build(): array {
		return array(
			'Tap to interact'                => __( 'Tap to interact', 'mapsemble' ),
			'Filters'                        => __( 'Filters', 'mapsemble' ),
			'More Filters'                   => __( 'More Filters', 'mapsemble' ),
			'All Filters'                    => __( 'All Filters', 'mapsemble' ),
			'Search'                         => __( 'Search', 'mapsemble' ),
			'Sort by'                        => __( 'Sort by', 'mapsemble' ),
			'No results found'               => __( 'No results found', 'mapsemble' ),
			'Try changing your search criteria or zooming out' => __( 'Try changing your search criteria or zooming out', 'mapsemble' ),
			'Reset'                          => __( 'Reset', 'mapsemble' ),
			'Erase'                          => __( 'Erase', 'mapsemble' ),
			'Erase all'                      => __( 'Erase all', 'mapsemble' ),
			'Clear'                          => __( 'Clear', 'mapsemble' ),
			'Close'                          => __( 'Close', 'mapsemble' ),
			'Apply'                          => __( 'Apply', 'mapsemble' ),
			'Display'                        => __( 'Display', 'mapsemble' ),
			'From'                           => __( 'From', 'mapsemble' ),
			'To'                             => __( 'To', 'mapsemble' ),
			'1 item matches your search'     => __( '1 item matches your search', 'mapsemble' ),
			/* translators: @count is replaced by the widget itself; keep it verbatim, it is not a PHP placeholder. */
			'@count items match your search' => __( '@count items match your search', 'mapsemble' ),
			'result'                         => __( 'result', 'mapsemble' ),
			'results'                        => __( 'results', 'mapsemble' ),
		);
	}

	/**
	 * The table worth shipping to the widget, or null when there is none.
	 *
	 * Ships the *full* table once anything differs: untranslated entries
	 * ride along as their English sources, which are identical to the
	 * widget's own defaults, so a partial table (with unverified merge
	 * semantics upstream) is never sent.
	 *
	 * @return array<string, string>|null
	 */
	public function for_widget(): ?array {
		/**
		 * Filters the widget translations table before the worth-shipping check.
		 *
		 * The seam for dynamic, Mapsemble-sourced strings and site overrides.
		 *
		 * @param array<string, string> $table source => translated.
		 */
		$table = (array) apply_filters( 'mapsemble_widget_translations', $this->build() );

		foreach ( $table as $source => $translated ) {
			if ( (string) $source !== (string) $translated ) {
				return $table;
			}
		}
		return null;
	}
}