<?php
declare(strict_types=1);

namespace Ekesto\CacheWarmup\Multilingual;

/**
 * Resolves multilingual context for counting, URL ordering, and permalink mapping.
 */
interface LanguageAdapterInterface
{
    /**
     * Whether this multilingual adapter is active.
     *
     * @return bool True when adapter integrations are available.
     */
    public function isActive(): bool;

    /**
     * Stable adapter key used in deterministic planning snapshots.
     *
     * @return string Lowercased adapter key.
     */
    public function getKey(): string;

    /**
     * Default (main) language code for the site.
     *
     * @return string|null Language code or null when unresolved.
     */
    public function getDefaultLanguage(): ?string;

    /**
     * Language code for a post in multilingual context.
     *
     * @param int $postId WordPress post ID.
     * @param string $postType Post type key.
     * @return string|null Language code or null when unresolved.
     */
    public function getPostLanguage(int $postId, string $postType): ?string;

    /**
     * Language code for a URL in multilingual context.
     *
     * @param string $url Absolute URL.
     * @return string|null Language code or null when unresolved.
     */
    public function getUrlLanguage(string $url): ?string;

    /**
     * Resolve a post permalink in multilingual context.
     *
     * @param int $postId WordPress post ID.
     * @param string $postType Post type key.
     * @param string $url Raw permalink URL.
     * @return string Multilingual-aware permalink URL.
     */
    public function resolvePostPermalink(int $postId, string $postType, string $url): string;
}
