first commit

lib/pkp/classes/i18n/interfaces/LocaleInterface.php

@@ -0,0 +1,172 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * @defgroup i18n I18N
+ * Implements localization concerns such as locale files, time zones, and country lists.
+ */
+
+/**
+ * @file classes/i18n/interfaces/LocaleInterface.php
+ *
+ * Copyright (c) 2014-2021 Simon Fraser University
+ * Copyright (c) 2000-2021 John Willinsky
+ * Distributed under the GNU GPL v3. For full terms see the file docs/COPYING.
+ *
+ * @class LocaleInterface
+ *
+ * @ingroup i18n
+ *
+ * @brief Provides methods for loading gettext locale files and translating texts
+ */
+
+namespace PKP\i18n\interfaces;
+
+use PKP\i18n\LocaleMetadata;
+use PKP\i18n\translation\LocaleBundle;
+use Sokil\IsoCodes\Database\Countries;
+use Sokil\IsoCodes\Database\Currencies;
+use Sokil\IsoCodes\Database\LanguagesInterface;
+use Sokil\IsoCodes\Database\Scripts;
+
+interface LocaleInterface extends \Illuminate\Contracts\Translation\Translator
+{
+    /** Keeps the default locale of the application */
+    public const DEFAULT_LOCALE = 'en';
+
+    /** Regular expression to validate and extract pieces of a locale code */
+    public const LOCALE_EXPRESSION = '/^(?P<language>[a-z]{2})(?:_(?P<country>[A-Za-z]{2,4}))?(?:@(?P<script>[A-Za-z\d]{5,8}|\d[A-Za-z\d]{3}))?$/';
+
+    /**
+     * Attempts to retrieve the primary locale for the current context, if not available, then for the site.
+     *
+     * @deprecated 3.4.0 Use Context::getPrimaryLocale()
+     */
+    public function getPrimaryLocale(): string;
+
+    /**
+     * Register a locale folder
+     *
+     * @param string $path The given folder is expected to have sub-folders, each one representing a locale (e.g. "./en").
+     * The application will then look for .po files and attempt to lazy load them when requested.
+     * @param int $priority The priority controls which locale should be loaded first, higher priorities overwrite smaller ones (in case of locale key conflicts), the default is 0
+     */
+    public function registerPath(string $path, int $priority = 0): void;
+
+    /**
+     * Register a locale file loader
+     *
+     * @param callable $fileLoader Receives two arguments.
+     * string $locale The locale string
+     * array $localeFiles An array (key = file path, value = the loading priority) with the locale files to be loaded.
+     * The second argument might be received as a reference (&) in order to update the locales.
+     * The $fileLoader will be invoked once when loading a locale.
+     * @param int $priority Defines the calling priority, higher values will be called later, the default is 0
+     */
+    public function registerLoader(callable $fileLoader, int $priority = 0): void;
+
+    /**
+     * Check if the supplied locale is valid.
+     */
+    public function isLocaleValid(?string $locale): bool;
+
+    /**
+     * Retrieves the metadata of a locale
+     */
+    public function getMetadata(string $locale): ?LocaleMetadata;
+
+    /**
+     * Retrieves a list of available locales with their metadata
+
+     *
+     * @return LocaleMetadata[]
+     */
+    public function getLocales(): array;
+
+    /**
+     * Install support for a new locale.
+     */
+    public function installLocale(string $locale): void;
+
+    /**
+     * Uninstall support for an existing locale.
+     */
+    public function uninstallLocale(string $locale): void;
+
+    /**
+     * Retrieves whether the given locale is in the list of supported locales
+     */
+    public function isSupported(string $locale): bool;
+
+    /**
+     * Get all supported form locales for the current context (if not available, then from the site).
+     *
+     * @deprecated 3.4.0 Use Context::getSupportedFormLocales()
+     *
+     * @return string[]
+     */
+    public function getSupportedFormLocales(): array;
+
+    /**
+     * Get all supported locales for the current context (if not available, then from the site).
+     *
+     * @deprecated 3.4.0 Use Context::getSupportedLocales()
+     *
+     * @return string[]
+     */
+    public function getSupportedLocales(): array;
+
+    /**
+     * Sets the handler to format missing locale keys
+     */
+    public function setMissingKeyHandler(?callable $handler): void;
+
+    /**
+     * Retrieves the handler to format missing locale keys
+     */
+    public function getMissingKeyHandler(): ?callable;
+
+    /**
+     * Retrieves a locale bundle to translate texts.
+     *
+     */
+    public function getBundle(?string $locale = null, bool $useCache = true): LocaleBundle;
+
+    /**
+     * Retrieves the default locale
+     */
+    public function getDefaultLocale(): string;
+
+    /**
+     * Retrieve the countries
+     */
+    public function getCountries(?string $locale = null): Countries;
+
+    /**
+     * Retrieve the currencies
+     */
+    public function getCurrencies(?string $locale = null): Currencies;
+
+    /**
+     * Retrieve the languages
+     */
+    public function getLanguages(?string $locale = null, bool $fromCache = true): LanguagesInterface;
+
+    /**
+     * Retrieve the scripts
+     */
+    public function getScripts(?string $locale = null): Scripts;
+
+    /**
+     * Get the formatted locale display names with country if same language code present multiple times
+     *
+     * @param array $filterByLocales Optional list of locales code to filter by the returned formatted names list
+     * @param array $locales Optional list of available all locales
+     * @param int $langLocaleStatus The const value of one of LocaleMetadata:LANGUAGE_LOCALE_*
+     * @param bool $omitLocaleCodeInDisplay Should leave out the locale code from display. By default leave out.
+     *
+     * @return array The list of locales with formatted display name
+     */
+    public function getFormattedDisplayNames(array $filterByLocales = null, array $locales = null, int $langLocaleStatus = LocaleMetadata::LANGUAGE_LOCALE_WITH, bool $omitLocaleCodeInDisplay = true): array;
+}