<?php

declare(strict_types=1);

namespace Signocore\Multilanguage\Admin;

if (!defined('ABSPATH')) {
	exit;
}

use Signocore\Multilanguage\Application\Constants;
use Signocore\Multilanguage\Application\LicenseManager;
use Signocore\Multilanguage\Infrastructure\Traits\Singleton;

/**
 * Guide page for the Signocore Multilanguage plugin admin area.
 */
final class GuidePage
{
	use Singleton;

	protected function init(): void {}

	/**
	 * Main render method for the guide page.
	 */
	public function render(): void
	{
		if (!current_user_can('manage_options')) {
			return;
		}

		$currentTab = isset($_GET['tab']) ? sanitize_text_field($_GET['tab']) : 'getting-started';

		$tabs = [
			'getting-started'     => __('Getting Started', 'signocore-multilanguage'),
			'translating-content' => __('Translating Content', 'signocore-multilanguage'),
			'url-configuration'   => __('URL Configuration', 'signocore-multilanguage'),
			'language-switcher'   => __('Language Switcher', 'signocore-multilanguage'),
			'developer-api'       => __('Developer API', 'signocore-multilanguage'),
		];

		?>
		<div class="wrap">
			<h1 class="sml-page-title">
				<?php echo esc_html__('Guide', 'signocore-multilanguage'); ?>
				<span class="sml-version"><?php echo esc_html('v' . Constants::$pluginVersion); ?></span>
			</h1>

			<h2 class="nav-tab-wrapper sml-tabs">
				<?php foreach ($tabs as $slug => $label) : ?>
					<a href="<?php echo esc_url(admin_url('admin.php?page=signocore-ml-guide&tab=' . $slug)); ?>"
					   class="nav-tab <?php echo $currentTab === $slug ? 'nav-tab-active' : ''; ?>">
						<?php echo esc_html($label); ?>
					</a>
				<?php endforeach; ?>
			</h2>

			<?php
			match ($currentTab) {
				'getting-started'     => $this->renderGettingStarted(),
				'translating-content' => $this->renderTranslatingContent(),
				'url-configuration'   => $this->renderUrlConfiguration(),
				'language-switcher'   => $this->renderLanguageSwitcher(),
				'developer-api'       => $this->renderDeveloperApi(),
				default               => $this->renderGettingStarted(),
			};
			?>
		</div>
		<?php
	}

	/**
	 * Render the Pro badge for features only available on the Pro plan.
	 */
	private function renderProBadge(): string
	{
		if (LicenseManager::load()->isPro()) {
			return '';
		}

		return ' <span class="sml-pro-badge">' . esc_html__('Pro', 'signocore-multilanguage') . '</span>';
	}

	// -------------------------------------------------------------------------
	// Tab 1: Getting Started
	// -------------------------------------------------------------------------

	private function renderGettingStarted(): void
	{
		$features = [
			[
				'icon' => 'dashicons-admin-page',
				'title' => __('Post & Page Translation', 'signocore-multilanguage'),
				'description' => __('Translate posts, pages, and custom post types with linked translations.', 'signocore-multilanguage'),
				'pro' => false,
			],
			[
				'icon' => 'dashicons-category',
				'title' => __('Taxonomy Translation', 'signocore-multilanguage'),
				'description' => __('Translate categories, tags, and custom taxonomies.', 'signocore-multilanguage'),
				'pro' => false,
			],
			[
				'icon' => 'dashicons-admin-media',
				'title' => __('Media Translation', 'signocore-multilanguage'),
				'description' => __('Localized titles, alt text, and captions per language.', 'signocore-multilanguage'),
				'pro' => false,
			],
			[
				'icon' => 'dashicons-editor-textcolor',
				'title' => __('String Translation', 'signocore-multilanguage'),
				'description' => __('Translate theme and plugin strings like widget titles and taglines.', 'signocore-multilanguage'),
				'pro' => false,
			],
			[
				'icon' => 'dashicons-randomize',
				'title' => __('Language Switcher', 'signocore-multilanguage'),
				'description' => __('Dropdown, list, flags, or inline switcher via widget, block, or shortcode.', 'signocore-multilanguage'),
				'pro' => false,
			],
			[
				'icon' => 'dashicons-admin-links',
				'title' => __('Directory URLs', 'signocore-multilanguage'),
				'description' => __('Language as directory prefix (e.g. example.com/da/).', 'signocore-multilanguage'),
				'pro' => false,
			],
			[
				'icon' => 'dashicons-code-standards',
				'title' => __('Hreflang Tags', 'signocore-multilanguage'),
				'description' => __('Automatic hreflang tags for SEO and search engine language targeting.', 'signocore-multilanguage'),
				'pro' => false,
			],
			[
				'icon' => 'dashicons-translation',
				'title' => __('Unlimited Languages', 'signocore-multilanguage'),
				'description' => __('Add as many languages as you need, beyond the free 2-language limit.', 'signocore-multilanguage'),
				'pro' => true,
			],
			[
				'icon' => 'dashicons-networking',
				'title' => __('Subdomain URLs', 'signocore-multilanguage'),
				'description' => __('Serve each language from its own subdomain (e.g. da.example.com).', 'signocore-multilanguage'),
				'pro' => true,
			],
			[
				'icon' => 'dashicons-admin-site-alt3',
				'title' => __('Custom Domain URLs', 'signocore-multilanguage'),
				'description' => __('Use a separate domain per language (e.g. example.dk).', 'signocore-multilanguage'),
				'pro' => true,
			],
			[
				'icon' => 'dashicons-tag',
				'title' => __('Permalink Translation', 'signocore-multilanguage'),
				'description' => __('Translate URL base slugs per language (e.g. /category/ to /kategori/).', 'signocore-multilanguage'),
				'pro' => true,
			],
			[
				'icon' => 'dashicons-controls-repeat',
				'title' => __('Shared Slugs', 'signocore-multilanguage'),
				'description' => __('Use the same post slug across languages for clean, consistent URLs.', 'signocore-multilanguage'),
				'pro' => true,
			],
			[
				'icon' => 'dashicons-cart',
				'title' => __('WooCommerce', 'signocore-multilanguage'),
				'description' => __('Translate products, categories, cart items, and shop pages.', 'signocore-multilanguage'),
				'pro' => true,
			],
			[
				'icon' => 'dashicons-layout',
				'title' => __('Elementor', 'signocore-multilanguage'),
				'description' => __('Translate Elementor-built pages and templates.', 'signocore-multilanguage'),
				'pro' => true,
			],
		];

		?>
		<div class="sml-guide-section">
			<div class="sml-card">
				<div class="sml-card-header">
					<h3><?php echo esc_html__('Welcome to Signocore Multilanguage', 'signocore-multilanguage'); ?></h3>
				</div>
				<div class="sml-card-body">
					<p>
						<?php echo esc_html__('Everything you need to create a fully multilingual WordPress site.', 'signocore-multilanguage'); ?>
					</p>
					<div class="sml-guide-features">
						<?php foreach ($features as $feature) : ?>
							<div class="sml-guide-method">
								<div class="sml-guide-method-header">
									<span class="dashicons <?php echo esc_attr($feature['icon']); ?>"></span>
									<strong><?php echo esc_html($feature['title']); ?></strong>
									<?php if ($feature['pro']) : ?>
										<?php echo wp_kses_post($this->renderProBadge()); ?>
									<?php endif; ?>
								</div>
								<p><?php echo esc_html($feature['description']); ?></p>
							</div>
						<?php endforeach; ?>
					</div>
				</div>
			</div>

			<div class="sml-card">
				<div class="sml-card-header">
					<h3><?php echo esc_html__('Quick Start', 'signocore-multilanguage'); ?></h3>
				</div>
				<div class="sml-card-body">
					<ol>
						<li>
							<strong><?php echo esc_html__('Add languages', 'signocore-multilanguage'); ?></strong> —
							<?php
							printf(
								/* translators: %s: link to languages settings page */
								esc_html__('Go to %s and add the languages you need.', 'signocore-multilanguage'),
								'<a href="' . esc_url(admin_url('admin.php?page=signocore-ml-languages')) . '">' . esc_html__('Settings > Languages', 'signocore-multilanguage') . '</a>'
							);
							?>
						</li>
						<li>
							<strong><?php echo esc_html__('Translate content', 'signocore-multilanguage'); ?></strong> —
							<?php echo esc_html__('Edit any post or page and use the translation metabox in the sidebar to create translations in each language.', 'signocore-multilanguage'); ?>
						</li>
						<li>
							<strong><?php echo esc_html__('Set up the language switcher', 'signocore-multilanguage'); ?></strong> —
							<?php echo esc_html__('Add a language switcher to your site using a widget, block, shortcode, or automatic menu injection.', 'signocore-multilanguage'); ?>
						</li>
						<li>
							<strong><?php echo esc_html__('Configure URLs', 'signocore-multilanguage'); ?></strong> —
							<?php
							printf(
								/* translators: %s: link to URL settings page */
								esc_html__('Choose your preferred URL strategy in %s.', 'signocore-multilanguage'),
								'<a href="' . esc_url(admin_url('admin.php?page=signocore-ml-settings&tab=urls')) . '">' . esc_html__('Settings > URLs tab', 'signocore-multilanguage') . '</a>'
							);
							?>
						</li>
					</ol>
				</div>
			</div>

			<div class="sml-card">
				<div class="sml-card-header">
					<h3><?php echo esc_html__('Setup Wizard', 'signocore-multilanguage'); ?></h3>
				</div>
				<div class="sml-card-body">
					<p>
						<?php echo esc_html__('The setup wizard walks you through the initial configuration of languages, URL strategy, and more. If you need to re-run it, you can do so from the Dashboard page.', 'signocore-multilanguage'); ?>
					</p>
				</div>
			</div>
		</div>
		<?php
	}

	// -------------------------------------------------------------------------
	// Tab 2: Translating Content
	// -------------------------------------------------------------------------

	private function renderTranslatingContent(): void
	{
		?>
		<div class="sml-guide-section">
			<div class="sml-card">
				<div class="sml-card-header">
					<h3><?php echo esc_html__('Posts & Pages', 'signocore-multilanguage'); ?></h3>
				</div>
				<div class="sml-card-body">
					<p>
						<?php echo esc_html__('Each post and page displays a translation metabox in the editor sidebar. The metabox shows all active languages with a flag icon for each. Click a flag to create a translation — this will create a new post that is linked to the original. Each translation is an independent post that you can edit freely with its own title, content, featured image, and other fields.', 'signocore-multilanguage'); ?>
					</p>
				</div>
			</div>

			<div class="sml-card">
				<div class="sml-card-header">
					<h3><?php echo esc_html__('Custom Post Types', 'signocore-multilanguage'); ?></h3>
				</div>
				<div class="sml-card-body">
					<p>
						<?php echo esc_html__('Custom post types follow the same workflow as posts and pages. The translation metabox appears automatically for all translatable post types.', 'signocore-multilanguage'); ?>
					</p>
					<p>
						<?php
						printf(
							/* translators: %s: link to general settings page */
							esc_html__('Configure which post types are translatable in %s.', 'signocore-multilanguage'),
							'<a href="' . esc_url(admin_url('admin.php?page=signocore-ml-settings&tab=general')) . '">' . esc_html__('Settings > General tab', 'signocore-multilanguage') . '</a>'
						);
						?>
					</p>
				</div>
			</div>

			<div class="sml-card">
				<div class="sml-card-header">
					<h3><?php echo esc_html__('Categories & Tags', 'signocore-multilanguage'); ?></h3>
				</div>
				<div class="sml-card-body">
					<p>
						<?php echo esc_html__('Taxonomies can be translated in the same way as posts. When you edit a category or tag, a translation panel is available. Click a flag to create the translated term, then edit its name and slug independently.', 'signocore-multilanguage'); ?>
					</p>
				</div>
			</div>

			<div class="sml-card">
				<div class="sml-card-header">
					<h3><?php echo esc_html__('Custom Taxonomies', 'signocore-multilanguage'); ?></h3>
				</div>
				<div class="sml-card-body">
					<p>
						<?php echo esc_html__('Custom taxonomies work identically to categories and tags. The translation panel appears on the term edit screen.', 'signocore-multilanguage'); ?>
					</p>
					<p>
						<?php
						printf(
							/* translators: %s: link to general settings page */
							esc_html__('Configure which taxonomies are translatable in %s.', 'signocore-multilanguage'),
							'<a href="' . esc_url(admin_url('admin.php?page=signocore-ml-settings&tab=general')) . '">' . esc_html__('Settings > General tab', 'signocore-multilanguage') . '</a>'
						);
						?>
					</p>
				</div>
			</div>

			<div class="sml-card">
				<div class="sml-card-header">
					<h3><?php echo esc_html__('Media Library', 'signocore-multilanguage'); ?></h3>
				</div>
				<div class="sml-card-body">
					<p>
						<?php echo esc_html__('Attachments can be translated. Each media item has a translation panel in the attachment edit screen. This allows you to provide localized titles, alt text, captions, and descriptions for each language.', 'signocore-multilanguage'); ?>
					</p>
				</div>
			</div>

			<div class="sml-card">
				<div class="sml-card-header">
					<h3><?php echo esc_html__('Menus', 'signocore-multilanguage'); ?></h3>
				</div>
				<div class="sml-card-body">
					<p>
						<?php echo esc_html__('Create separate navigation menus for each language. You can assign language-specific menus in Settings > General tab under "Navigation Menus". Each menu can contain different items tailored to that language audience.', 'signocore-multilanguage'); ?>
					</p>
				</div>
			</div>

			<div class="sml-card">
				<div class="sml-card-header">
					<h3><?php echo esc_html__('String Translation', 'signocore-multilanguage'); ?></h3>
				</div>
				<div class="sml-card-body">
					<p>
						<?php echo esc_html__('For theme and plugin strings such as widget titles, taglines, and other hard-coded text, use the String Translation feature. Strings are auto-scanned from your active theme and plugins.', 'signocore-multilanguage'); ?>
					</p>
					<p>
						<?php
						printf(
							/* translators: %s: link to string translation page */
							esc_html__('Access it via %s.', 'signocore-multilanguage'),
							'<a href="' . esc_url(admin_url('admin.php?page=signocore-ml-strings')) . '">' . esc_html__('Signocore ML > String Translation', 'signocore-multilanguage') . '</a>'
						);
						?>
					</p>
				</div>
			</div>

			<div class="sml-card">
				<div class="sml-card-header">
					<h3><?php echo esc_html__('Translation Workflow', 'signocore-multilanguage'); ?></h3>
				</div>
				<div class="sml-card-body">
					<p><?php echo esc_html__('Recommended best practices for translating your site:', 'signocore-multilanguage'); ?></p>
					<ol>
						<li><?php echo esc_html__('Create all content in the default language first.', 'signocore-multilanguage'); ?></li>
						<li><?php echo esc_html__('Create translations from the original post (this preserves the linking between translations).', 'signocore-multilanguage'); ?></li>
						<li><?php echo esc_html__('Use "Copy Source Content" to start with a copy of the original content, then translate it.', 'signocore-multilanguage'); ?></li>
						<li><?php echo esc_html__('Translate and publish each translation when it is ready.', 'signocore-multilanguage'); ?></li>
					</ol>
				</div>
			</div>
		</div>
		<?php
	}

	// -------------------------------------------------------------------------
	// Tab 3: URL Configuration
	// -------------------------------------------------------------------------

	private function renderUrlConfiguration(): void
	{
		?>
		<div class="sml-guide-section">
			<div class="sml-card">
				<div class="sml-card-header">
					<h3><?php echo esc_html__('Directory Prefix', 'signocore-multilanguage'); ?></h3>
				</div>
				<div class="sml-card-body">
					<p>
						<?php echo esc_html__('The default URL strategy. A language code is added as a directory prefix in the URL path.', 'signocore-multilanguage'); ?>
					</p>
					<code class="sml-guide-code">example.com/da/page-slug
example.com/en/page-slug</code>
					<p style="margin-top: 12px;">
						<?php echo esc_html__('The default language can optionally hide the prefix (see "Hide Default Language Prefix" below).', 'signocore-multilanguage'); ?>
					</p>
				</div>
			</div>

			<div class="sml-card">
				<div class="sml-card-header">
					<h3><?php echo wp_kses_post(__('Subdomain', 'signocore-multilanguage') . $this->renderProBadge()); ?></h3>
				</div>
				<div class="sml-card-body">
					<p>
						<?php echo esc_html__('Each language lives on its own subdomain. This requires DNS configuration to point each subdomain to your server.', 'signocore-multilanguage'); ?>
					</p>
					<code class="sml-guide-code">da.example.com/page-slug
en.example.com/page-slug</code>
				</div>
			</div>

			<div class="sml-card">
				<div class="sml-card-header">
					<h3><?php echo wp_kses_post(__('Custom Domain', 'signocore-multilanguage') . $this->renderProBadge()); ?></h3>
				</div>
				<div class="sml-card-body">
					<p>
						<?php echo esc_html__('Each language can be served from a completely separate domain. This requires domain registration, DNS configuration, and server setup for each domain.', 'signocore-multilanguage'); ?>
					</p>
					<code class="sml-guide-code">example.dk/page-slug
example.com/page-slug</code>
				</div>
			</div>

			<div class="sml-card">
				<div class="sml-card-header">
					<h3><?php echo wp_kses_post(__('Permalink Translation', 'signocore-multilanguage') . $this->renderProBadge()); ?></h3>
				</div>
				<div class="sml-card-body">
					<p>
						<?php echo esc_html__('Translate URL base slugs per language. For example, the /category/ base can become /kategori/ in Danish, or /product/ can become /produkt/.', 'signocore-multilanguage'); ?>
					</p>
					<code class="sml-guide-code">example.com/category/news &rarr; example.com/da/kategori/nyheder</code>
					<p style="margin-top: 12px;">
						<?php
						printf(
							/* translators: %s: link to URL settings page */
							esc_html__('Configure permalink translations in %s.', 'signocore-multilanguage'),
							'<a href="' . esc_url(admin_url('admin.php?page=signocore-ml-settings&tab=urls')) . '">' . esc_html__('Settings > URLs tab', 'signocore-multilanguage') . '</a>'
						);
						?>
					</p>
				</div>
			</div>

			<div class="sml-card">
				<div class="sml-card-header">
					<h3><?php echo esc_html__('Hide Default Language Prefix', 'signocore-multilanguage'); ?></h3>
				</div>
				<div class="sml-card-body">
					<p>
						<?php echo esc_html__('When enabled, the default language URLs do not include a language code in the path. Non-default languages always include their language code.', 'signocore-multilanguage'); ?>
					</p>
					<code class="sml-guide-code">example.com/page-slug        &larr; <?php echo esc_html__('default language (no prefix)', 'signocore-multilanguage'); ?>

example.com/da/page-slug     &larr; <?php echo esc_html__('non-default language', 'signocore-multilanguage'); ?></code>
				</div>
			</div>
		</div>
		<?php
	}

	// -------------------------------------------------------------------------
	// Tab 4: Language Switcher
	// -------------------------------------------------------------------------

	private function renderLanguageSwitcher(): void
	{
		?>
		<div class="sml-guide-section">
			<div class="sml-card">
				<div class="sml-card-header">
					<h3><?php echo esc_html__('Shortcode', 'signocore-multilanguage'); ?></h3>
				</div>
				<div class="sml-card-body">
					<p><?php echo esc_html__('Use the shortcode in any post, page, or widget area:', 'signocore-multilanguage'); ?></p>
					<code class="sml-guide-code">[signocore_language_switcher]</code>
					<p style="margin-top: 12px;"><?php echo esc_html__('Available attributes:', 'signocore-multilanguage'); ?></p>
					<table class="sml-guide-table">
						<thead>
							<tr>
								<th><?php echo esc_html__('Attribute', 'signocore-multilanguage'); ?></th>
								<th><?php echo esc_html__('Values', 'signocore-multilanguage'); ?></th>
								<th><?php echo esc_html__('Description', 'signocore-multilanguage'); ?></th>
							</tr>
						</thead>
						<tbody>
							<tr>
								<td><code>style</code></td>
								<td><code>dropdown</code>, <code>list</code>, <code>flags</code>, <code>inline</code></td>
								<td><?php echo esc_html__('Display style of the switcher', 'signocore-multilanguage'); ?></td>
							</tr>
							<tr>
								<td><code>show_flags</code></td>
								<td><code>true</code> / <code>false</code></td>
								<td><?php echo esc_html__('Show flag icons', 'signocore-multilanguage'); ?></td>
							</tr>
							<tr>
								<td><code>show_names</code></td>
								<td><code>true</code> / <code>false</code></td>
								<td><?php echo esc_html__('Show language names', 'signocore-multilanguage'); ?></td>
							</tr>
							<tr>
								<td><code>show_native_names</code></td>
								<td><code>true</code> / <code>false</code></td>
								<td><?php echo esc_html__('Show native language names', 'signocore-multilanguage'); ?></td>
							</tr>
							<tr>
								<td><code>show_current</code></td>
								<td><code>true</code> / <code>false</code></td>
								<td><?php echo esc_html__('Include the current language in the list', 'signocore-multilanguage'); ?></td>
							</tr>
							<tr>
								<td><code>skip_missing</code></td>
								<td><code>true</code> / <code>false</code></td>
								<td><?php echo esc_html__('Hide languages without a translation for the current content', 'signocore-multilanguage'); ?></td>
							</tr>
							<tr>
								<td><code>class</code></td>
								<td><?php echo esc_html__('CSS class name', 'signocore-multilanguage'); ?></td>
								<td><?php echo esc_html__('Add a custom CSS class to the wrapper', 'signocore-multilanguage'); ?></td>
							</tr>
						</tbody>
					</table>
					<p style="margin-top: 12px;"><?php echo esc_html__('Example with attributes:', 'signocore-multilanguage'); ?></p>
					<code class="sml-guide-code">[signocore_language_switcher style="inline" show_flags="true" show_names="false"]</code>
				</div>
			</div>

			<div class="sml-card">
				<div class="sml-card-header">
					<h3><?php echo esc_html__('PHP Function', 'signocore-multilanguage'); ?></h3>
				</div>
				<div class="sml-card-body">
					<p><?php echo esc_html__('Call the template function anywhere in your theme files. It returns an HTML string.', 'signocore-multilanguage'); ?></p>
					<code class="sml-guide-code">&lt;?php echo signocore_language_switcher(['style' =&gt; 'dropdown']); ?&gt;</code>
					<p style="margin-top: 12px;"><?php echo esc_html__('Accepts the same options as the shortcode attributes.', 'signocore-multilanguage'); ?></p>
				</div>
			</div>

			<div class="sml-card">
				<div class="sml-card-header">
					<h3><?php echo esc_html__('Widget', 'signocore-multilanguage'); ?></h3>
				</div>
				<div class="sml-card-body">
					<p>
						<?php
						printf(
							/* translators: %s: link to widgets page */
							esc_html__('A "Language Switcher" widget is available in %s. Add it to any widget area and configure style, flags, and name display from the widget settings.', 'signocore-multilanguage'),
							'<a href="' . esc_url(admin_url('widgets.php')) . '">' . esc_html__('Appearance > Widgets', 'signocore-multilanguage') . '</a>'
						);
						?>
					</p>
				</div>
			</div>

			<div class="sml-card">
				<div class="sml-card-header">
					<h3><?php echo esc_html__('Gutenberg Block', 'signocore-multilanguage'); ?></h3>
				</div>
				<div class="sml-card-body">
					<p>
						<?php echo esc_html__('A "Language Switcher" block is available in the block editor. Click the inserter (+) and search for "Language Switcher". Style, flags, and names can be configured in the block settings panel.', 'signocore-multilanguage'); ?>
					</p>
				</div>
			</div>

			<div class="sml-card">
				<div class="sml-card-header">
					<h3><?php echo esc_html__('Menu Integration', 'signocore-multilanguage'); ?></h3>
				</div>
				<div class="sml-card-body">
					<p>
						<?php echo esc_html__('Automatically inject language links into a navigation menu. The switcher items are appended (or prepended) to your existing menu.', 'signocore-multilanguage'); ?>
					</p>
					<p>
						<?php
						printf(
							/* translators: %s: link to switcher settings page */
							esc_html__('Configure which menus receive the switcher and the position in %s.', 'signocore-multilanguage'),
							'<a href="' . esc_url(admin_url('admin.php?page=signocore-ml-settings&tab=switcher')) . '">' . esc_html__('Settings > Switcher tab', 'signocore-multilanguage') . '</a>'
						);
						?>
					</p>
				</div>
			</div>

			<div class="sml-card">
				<div class="sml-card-header">
					<h3><?php echo esc_html__('Available Styles', 'signocore-multilanguage'); ?></h3>
				</div>
				<div class="sml-card-body">
					<table class="sml-guide-table">
						<thead>
							<tr>
								<th><?php echo esc_html__('Style', 'signocore-multilanguage'); ?></th>
								<th><?php echo esc_html__('Description', 'signocore-multilanguage'); ?></th>
							</tr>
						</thead>
						<tbody>
							<tr>
								<td><code>dropdown</code></td>
								<td><?php echo esc_html__('An expandable button that reveals a dropdown list of languages on click.', 'signocore-multilanguage'); ?></td>
							</tr>
							<tr>
								<td><code>list</code></td>
								<td><?php echo esc_html__('A vertical list showing all languages at once.', 'signocore-multilanguage'); ?></td>
							</tr>
							<tr>
								<td><code>flags</code></td>
								<td><?php echo esc_html__('Compact flag images only, without text labels.', 'signocore-multilanguage'); ?></td>
							</tr>
							<tr>
								<td><code>inline</code></td>
								<td><?php echo esc_html__('A horizontal row of language links separated by dividers.', 'signocore-multilanguage'); ?></td>
							</tr>
						</tbody>
					</table>
				</div>
			</div>

			<div class="sml-card">
				<div class="sml-card-header">
					<h3><?php echo esc_html__('Customization', 'signocore-multilanguage'); ?></h3>
				</div>
				<div class="sml-card-body">
					<p>
						<?php echo esc_html__('Use the following filters to customize the language switcher output:', 'signocore-multilanguage'); ?>
					</p>
					<p>
						<strong><code>signocore_ml_switcher_html</code></strong> —
						<?php echo esc_html__('Completely replace the rendered HTML of the switcher.', 'signocore-multilanguage'); ?>
					</p>
					<code class="sml-guide-code"><pre>add_filter('signocore_ml_switcher_html', function (string $html, array $args, array $links): string {
    // Return your custom HTML
    return $html;
}, 10, 3);</pre></code>
					<p style="margin-top: 12px;">
						<strong><code>signocore_ml_language_links</code></strong> —
						<?php echo esc_html__('Modify the language link data array before it is rendered.', 'signocore-multilanguage'); ?>
					</p>
					<code class="sml-guide-code"><pre>add_filter('signocore_ml_language_links', function (array $links): array {
    // Modify $links array
    return $links;
});</pre></code>
				</div>
			</div>
		</div>
		<?php
	}

	// -------------------------------------------------------------------------
	// Tab 5: Developer API
	// -------------------------------------------------------------------------

	private function renderDeveloperApi(): void
	{
		?>
		<div class="sml-guide-section">
			<?php
			$this->renderDeveloperTemplateFunctions();
			$this->renderDeveloperQueryFiltering();
			$this->renderDeveloperActionHooks();
			$this->renderDeveloperFilterHooks();
			$this->renderDeveloperWpmlCompat();
			?>
		</div>
		<?php
	}

	/**
	 * Render the Template Functions section.
	 */
	private function renderDeveloperTemplateFunctions(): void
	{
		?>
		<div class="sml-card">
			<div class="sml-card-header">
				<h3><?php echo esc_html__('Template Functions', 'signocore-multilanguage'); ?></h3>
			</div>
			<div class="sml-card-body">
				<p><?php echo esc_html__('These functions are available globally in your theme and plugin code:', 'signocore-multilanguage'); ?></p>
				<table class="sml-guide-table">
					<thead>
						<tr>
							<th><?php echo esc_html__('Function', 'signocore-multilanguage'); ?></th>
							<th><?php echo esc_html__('Description', 'signocore-multilanguage'); ?></th>
						</tr>
					</thead>
					<tbody>
						<tr>
							<td><code>signocore_ml_get_current_language(): string</code></td>
							<td><?php echo esc_html__('Returns the current language code.', 'signocore-multilanguage'); ?></td>
						</tr>
						<tr>
							<td><code>signocore_ml_get_default_language(): string</code></td>
							<td><?php echo esc_html__('Returns the default language code.', 'signocore-multilanguage'); ?></td>
						</tr>
						<tr>
							<td><code>signocore_ml_get_active_languages(): array</code></td>
							<td><?php echo esc_html__('Returns an array of all active language objects.', 'signocore-multilanguage'); ?></td>
						</tr>
						<tr>
							<td><code>signocore_ml_get_translation(int $elementId, string $langCode, string $elementType = 'post'): ?int</code></td>
							<td><?php echo esc_html__('Returns the translated element ID for the given language, or null if no translation exists.', 'signocore-multilanguage'); ?></td>
						</tr>
						<tr>
							<td><code>signocore_ml_get_translations(int $elementId, string $elementType = 'post'): array</code></td>
							<td><?php echo esc_html__('Returns an associative array of all translations keyed by language code.', 'signocore-multilanguage'); ?></td>
						</tr>
						<tr>
							<td><code>signocore_ml_has_translation(int $elementId, string $langCode, string $elementType = 'post'): bool</code></td>
							<td><?php echo esc_html__('Checks whether a translation exists for the given element and language.', 'signocore-multilanguage'); ?></td>
						</tr>
						<tr>
							<td><code>signocore_ml_get_element_language(int $elementId): string</code></td>
							<td><?php echo esc_html__('Returns the language code of the given element.', 'signocore-multilanguage'); ?></td>
						</tr>
						<tr>
							<td><code>signocore_ml_switch_language(string $langCode): void</code></td>
							<td><?php echo esc_html__('Temporarily switches the active language context. Use with restore_language.', 'signocore-multilanguage'); ?></td>
						</tr>
						<tr>
							<td><code>signocore_ml_restore_language(): void</code></td>
							<td><?php echo esc_html__('Restores the language to the previous context after switch_language.', 'signocore-multilanguage'); ?></td>
						</tr>
						<tr>
							<td><code>signocore_ml_is_default_language(): bool</code></td>
							<td><?php echo esc_html__('Returns true if the current language is the default language.', 'signocore-multilanguage'); ?></td>
						</tr>
						<tr>
							<td><code>signocore_ml_get_posts(array $args = []): array</code></td>
							<td><?php echo esc_html__('Retrieves posts filtered by the current language. Accepts WP_Query arguments.', 'signocore-multilanguage'); ?></td>
						</tr>
						<tr>
							<td><code>signocore_ml_get_url_for_language(string $langCode, ?string $url = null): string</code></td>
							<td><?php echo esc_html__('Returns the URL for a specific language. If no URL is given, uses the current URL.', 'signocore-multilanguage'); ?></td>
						</tr>
						<tr>
							<td><code>signocore_ml_get_permalink(int $postId, string $langCode): ?string</code></td>
							<td><?php echo esc_html__('Returns the permalink for a post in the specified language.', 'signocore-multilanguage'); ?></td>
						</tr>
						<tr>
							<td><code>signocore_ml_translate_string(string $context, string $name, string $default = ''): string</code></td>
							<td><?php echo esc_html__('Returns the translated string for the current language from the string translation system.', 'signocore-multilanguage'); ?></td>
						</tr>
						<tr>
							<td><code>signocore_language_switcher(array $args = []): string</code></td>
							<td><?php echo esc_html__('Returns the language switcher HTML. Accepts the same options as the shortcode.', 'signocore-multilanguage'); ?></td>
						</tr>
					</tbody>
				</table>
			</div>
		</div>
		<?php
	}

	/**
	 * Render the Query Filtering section.
	 */
	private function renderDeveloperQueryFiltering(): void
	{
		?>
		<div class="sml-card">
			<div class="sml-card-header">
				<h3><?php echo esc_html__('Query Filtering', 'signocore-multilanguage'); ?></h3>
			</div>
			<div class="sml-card-body">
				<h4><?php echo esc_html__('Posts', 'signocore-multilanguage'); ?></h4>
				<p>
					<?php echo esc_html__('Only the main query is automatically filtered by language on the frontend. Secondary queries (get_posts, WP_Query) are NOT filtered by default. To filter a secondary query by the current language, use either of these approaches:', 'signocore-multilanguage'); ?>
				</p>
				<ul>
					<li>
						<?php
						printf(
							/* translators: %s: function name */
							esc_html__('Use %s which wraps WP_Query with language filtering built in.', 'signocore-multilanguage'),
							'<code>signocore_ml_get_posts()</code>'
						);
						?>
					</li>
					<li>
						<?php
						printf(
							/* translators: %1$s: first query parameter, %2$s: second query parameter */
							esc_html__('Set %1$s and %2$s in your WP_Query arguments.', 'signocore-multilanguage'),
							'<code>\'sml_filter_language\' => true</code>',
							'<code>\'suppress_filters\' => false</code>'
						);
						?>
					</li>
				</ul>

				<h4><?php echo esc_html__('Terms', 'signocore-multilanguage'); ?></h4>
				<p>
					<?php
					printf(
						/* translators: %1$s: function name, %2$s: hook name, %3$s: opt-out parameter */
						esc_html__('All frontend %1$s calls are automatically filtered by language after the %2$s action. To opt out and retrieve terms in all languages, pass %3$s in your query arguments.', 'signocore-multilanguage'),
						'<code>get_terms()</code>',
						'<code>wp</code>',
						'<code>\'sml_filter_language\' => false</code>'
					);
					?>
				</p>

				<h4><?php echo esc_html__('Language Switching', 'signocore-multilanguage'); ?></h4>
				<p>
					<?php
					printf(
						/* translators: %1$s: switch function, %2$s: restore function */
						esc_html__('Use %1$s and %2$s to temporarily query in a specific language context.', 'signocore-multilanguage'),
						'<code>signocore_ml_switch_language()</code>',
						'<code>signocore_ml_restore_language()</code>'
					);
					?>
				</p>

				<details class="sml-guide-details">
					<summary><?php echo esc_html__('View code examples', 'signocore-multilanguage'); ?></summary>

					<p style="margin-top: 12px;"><strong><?php echo esc_html__('Get posts in the current language:', 'signocore-multilanguage'); ?></strong></p>
					<code class="sml-guide-code"><pre>// Using the helper function (recommended)
$posts = signocore_ml_get_posts([
    'post_type'      => 'post',
    'posts_per_page' => 10,
]);

// Using WP_Query directly
$query = new WP_Query([
    'post_type'           => 'post',
    'posts_per_page'      => 10,
    'sml_filter_language' => true,
    'suppress_filters'    => false,
]);</pre></code>

					<p style="margin-top: 12px;"><strong><?php echo esc_html__('Get all terms regardless of language:', 'signocore-multilanguage'); ?></strong></p>
					<code class="sml-guide-code"><pre>$terms = get_terms([
    'taxonomy'            => 'category',
    'sml_filter_language' => false,
]);</pre></code>

					<p style="margin-top: 12px;"><strong><?php echo esc_html__('Query in a specific language context:', 'signocore-multilanguage'); ?></strong></p>
					<code class="sml-guide-code"><pre>signocore_ml_switch_language('da');

$danish_posts = signocore_ml_get_posts([
    'post_type'      => 'post',
    'posts_per_page' => 5,
]);

signocore_ml_restore_language();</pre></code>
				</details>
			</div>
		</div>
		<?php
	}

	/**
	 * Render the Action Hooks section.
	 */
	private function renderDeveloperActionHooks(): void
	{
		?>
		<div class="sml-card">
			<div class="sml-card-header">
				<h3><?php echo esc_html__('Action Hooks', 'signocore-multilanguage'); ?></h3>
			</div>
			<div class="sml-card-body">
				<table class="sml-guide-table">
					<thead>
						<tr>
							<th><?php echo esc_html__('Hook', 'signocore-multilanguage'); ?></th>
							<th><?php echo esc_html__('Parameters', 'signocore-multilanguage'); ?></th>
							<th><?php echo esc_html__('Description', 'signocore-multilanguage'); ?></th>
						</tr>
					</thead>
					<tbody>
						<tr>
							<td><code>signocore_ml_language_added</code></td>
							<td><code>string $code</code>, <code>array $data</code></td>
							<td><?php echo esc_html__('Fires when a new language is added.', 'signocore-multilanguage'); ?></td>
						</tr>
						<tr>
							<td><code>signocore_ml_language_removed</code></td>
							<td><code>string $code</code></td>
							<td><?php echo esc_html__('Fires when a language is removed.', 'signocore-multilanguage'); ?></td>
						</tr>
						<tr>
							<td><code>signocore_ml_language_updated</code></td>
							<td><code>string $code</code>, <code>array $data</code></td>
							<td><?php echo esc_html__('Fires when a language is updated.', 'signocore-multilanguage'); ?></td>
						</tr>
						<tr>
							<td><code>signocore_ml_default_language_changed</code></td>
							<td><code>string $code</code>, <code>string $oldCode</code></td>
							<td><?php echo esc_html__('Fires when the default language changes.', 'signocore-multilanguage'); ?></td>
						</tr>
						<tr>
							<td><code>signocore_ml_languages_changed</code></td>
							<td>&mdash;</td>
							<td><?php echo esc_html__('Fires whenever the language configuration changes (add, remove, update, reorder).', 'signocore-multilanguage'); ?></td>
						</tr>
						<tr>
							<td><code>signocore_ml_translation_created</code></td>
							<td><code>int $newPostId</code>, <code>int $sourcePostId</code>, <code>string $langCode</code>, <code>int $groupId</code></td>
							<td><?php echo esc_html__('Fires when a new post translation is created.', 'signocore-multilanguage'); ?></td>
						</tr>
						<tr>
							<td><code>signocore_ml_translation_linked</code></td>
							<td><code>int $targetPostId</code>, <code>int $sourcePostId</code>, <code>string $langCode</code>, <code>int $groupId</code></td>
							<td><?php echo esc_html__('Fires when an existing post is linked as a translation.', 'signocore-multilanguage'); ?></td>
						</tr>
						<tr>
							<td><code>signocore_ml_translation_unlinked</code></td>
							<td><code>int $postId</code>, <code>string $langCode</code></td>
							<td><?php echo esc_html__('Fires when a post translation link is removed.', 'signocore-multilanguage'); ?></td>
						</tr>
						<tr>
							<td><code>signocore_ml_translation_deleted</code></td>
							<td><code>int $postId</code>, <code>string $elementType</code></td>
							<td><?php echo esc_html__('Fires when a post translation record is deleted.', 'signocore-multilanguage'); ?></td>
						</tr>
						<tr>
							<td><code>signocore_ml_term_translation_created</code></td>
							<td><code>int $newTermId</code>, <code>int $sourceTermId</code>, <code>string $taxonomy</code>, <code>string $langCode</code>, <code>int $groupId</code></td>
							<td><?php echo esc_html__('Fires when a new term translation is created.', 'signocore-multilanguage'); ?></td>
						</tr>
						<tr>
							<td><code>signocore_ml_term_translation_linked</code></td>
							<td><code>int $targetTermId</code>, <code>int $sourceTermId</code>, <code>string $taxonomy</code>, <code>string $langCode</code>, <code>int $groupId</code></td>
							<td><?php echo esc_html__('Fires when an existing term is linked as a translation.', 'signocore-multilanguage'); ?></td>
						</tr>
						<tr>
							<td><code>signocore_ml_term_translation_unlinked</code></td>
							<td><code>int $termId</code>, <code>string $taxonomy</code>, <code>string $langCode</code></td>
							<td><?php echo esc_html__('Fires when a term translation link is removed.', 'signocore-multilanguage'); ?></td>
						</tr>
						<tr>
							<td><code>signocore_ml_term_translation_deleted</code></td>
							<td><code>int $termId</code>, <code>string $taxonomy</code>, <code>string $elementType</code></td>
							<td><?php echo esc_html__('Fires when a term translation record is deleted.', 'signocore-multilanguage'); ?></td>
						</tr>
						<tr>
							<td><code>signocore_ml_language_switched</code></td>
							<td><code>string $langCode</code>, <code>string $previousLangCode</code></td>
							<td><?php echo esc_html__('Fires after the language context is switched programmatically.', 'signocore-multilanguage'); ?></td>
						</tr>
						<tr>
							<td><code>signocore_ml_activated</code></td>
							<td>&mdash;</td>
							<td><?php echo esc_html__('Fires when the plugin is activated.', 'signocore-multilanguage'); ?></td>
						</tr>
						<tr>
							<td><code>signocore_ml_deactivated</code></td>
							<td>&mdash;</td>
							<td><?php echo esc_html__('Fires when the plugin is deactivated.', 'signocore-multilanguage'); ?></td>
						</tr>
					</tbody>
				</table>
			</div>
		</div>
		<?php
	}

	/**
	 * Render the Filter Hooks section.
	 */
	private function renderDeveloperFilterHooks(): void
	{
		?>
		<div class="sml-card">
			<div class="sml-card-header">
				<h3><?php echo esc_html__('Filter Hooks', 'signocore-multilanguage'); ?></h3>
			</div>
			<div class="sml-card-body">
				<table class="sml-guide-table">
					<thead>
						<tr>
							<th><?php echo esc_html__('Hook', 'signocore-multilanguage'); ?></th>
							<th><?php echo esc_html__('Parameters / Return', 'signocore-multilanguage'); ?></th>
							<th><?php echo esc_html__('Description', 'signocore-multilanguage'); ?></th>
						</tr>
					</thead>
					<tbody>
						<tr>
							<td><code>signocore_ml_translatable_post_types</code></td>
							<td><code>string[]</code> &rarr; <code>string[]</code></td>
							<td><?php echo esc_html__('Filter the list of post types that support translation.', 'signocore-multilanguage'); ?></td>
						</tr>
						<tr>
							<td><code>signocore_ml_translatable_taxonomies</code></td>
							<td><code>string[]</code> &rarr; <code>string[]</code></td>
							<td><?php echo esc_html__('Filter the list of taxonomies that support translation.', 'signocore-multilanguage'); ?></td>
						</tr>
						<tr>
							<td><code>signocore_ml_pre_duplicate_post</code></td>
							<td><code>array $postData</code>, <code>int $sourcePostId</code>, <code>string $langCode</code> &rarr; <code>array</code></td>
							<td><?php echo esc_html__('Modify the post data array before a translation duplicate is inserted.', 'signocore-multilanguage'); ?></td>
						</tr>
						<tr>
							<td><code>signocore_ml_post_meta_to_duplicate</code></td>
							<td><code>string[] $metaKeys</code>, <code>int $sourcePostId</code>, <code>string $langCode</code> &rarr; <code>string[]</code></td>
							<td><?php echo esc_html__('Filter which post meta keys are copied when creating a translation.', 'signocore-multilanguage'); ?></td>
						</tr>
						<tr>
							<td><code>sml_copy_content_excluded_meta_keys</code></td>
							<td><code>string[] $excludedKeys</code>, <code>int $sourcePostId</code>, <code>int $targetPostId</code> &rarr; <code>string[]</code></td>
							<td><?php echo esc_html__('Filter which meta keys are excluded when copying source content to a translation.', 'signocore-multilanguage'); ?></td>
						</tr>
						<tr>
							<td><code>signocore_ml_switcher_html</code></td>
							<td><code>string $html</code>, <code>array $args</code>, <code>array $links</code> &rarr; <code>string</code></td>
							<td><?php echo esc_html__('Completely replace the language switcher HTML output.', 'signocore-multilanguage'); ?></td>
						</tr>
						<tr>
							<td><code>signocore_ml_language_links</code></td>
							<td><code>array $links</code> &rarr; <code>array</code></td>
							<td><?php echo esc_html__('Modify the language links data before the switcher is rendered.', 'signocore-multilanguage'); ?></td>
						</tr>
						<tr>
							<td><code>signocore_ml_hreflang_tags</code></td>
							<td><code>array $tags</code> &rarr; <code>array</code></td>
							<td><?php echo esc_html__('Filter the hreflang link tags output in the page head.', 'signocore-multilanguage'); ?></td>
						</tr>
						<tr>
							<td><code>signocore_ml_url_for_language</code></td>
							<td><code>string $url</code>, <code>string $langCode</code>, <code>string $originalUrl</code> &rarr; <code>string</code></td>
							<td><?php echo esc_html__('Filter the generated URL for a specific language.', 'signocore-multilanguage'); ?></td>
						</tr>
						<tr>
							<td><code>signocore_ml_translatable_permalink_slugs</code></td>
							<td><code>array $slugs</code> &rarr; <code>array</code></td>
							<td><?php echo esc_html__('Filter the list of permalink slugs available for translation.', 'signocore-multilanguage'); ?></td>
						</tr>
					</tbody>
				</table>
			</div>
		</div>
		<?php
	}

	/**
	 * Render the WPML Compatibility section.
	 */
	private function renderDeveloperWpmlCompat(): void
	{
		?>
		<div class="sml-card">
			<div class="sml-card-header">
				<h3><?php echo esc_html__('WPML Compatibility', 'signocore-multilanguage'); ?></h3>
			</div>
			<div class="sml-card-body">
				<p>
					<?php echo esc_html__('Signocore Multilanguage provides WPML-compatible filter and action hooks. Plugins and themes that integrate with WPML using these hooks will work automatically without any additional configuration.', 'signocore-multilanguage'); ?>
				</p>
				<table class="sml-guide-table">
					<thead>
						<tr>
							<th><?php echo esc_html__('WPML Hook', 'signocore-multilanguage'); ?></th>
							<th><?php echo esc_html__('Description', 'signocore-multilanguage'); ?></th>
						</tr>
					</thead>
					<tbody>
						<tr>
							<td><code>wpml_object_id</code></td>
							<td><?php echo esc_html__('Get the translated element ID for a given language.', 'signocore-multilanguage'); ?></td>
						</tr>
						<tr>
							<td><code>wpml_current_language</code></td>
							<td><?php echo esc_html__('Get the current active language code.', 'signocore-multilanguage'); ?></td>
						</tr>
						<tr>
							<td><code>wpml_default_language</code></td>
							<td><?php echo esc_html__('Get the default language code.', 'signocore-multilanguage'); ?></td>
						</tr>
						<tr>
							<td><code>wpml_active_languages</code></td>
							<td><?php echo esc_html__('Get all active languages as an array.', 'signocore-multilanguage'); ?></td>
						</tr>
						<tr>
							<td><code>wpml_switch_language</code></td>
							<td><?php echo esc_html__('Switch the language context programmatically.', 'signocore-multilanguage'); ?></td>
						</tr>
						<tr>
							<td><code>wpml_element_has_translations</code></td>
							<td><?php echo esc_html__('Check if an element has translations in other languages.', 'signocore-multilanguage'); ?></td>
						</tr>
						<tr>
							<td><code>wpml_permalink</code></td>
							<td><?php echo esc_html__('Get the translated permalink for a post.', 'signocore-multilanguage'); ?></td>
						</tr>
						<tr>
							<td><code>wpml_home_url</code></td>
							<td><?php echo esc_html__('Get the home URL for a specific language.', 'signocore-multilanguage'); ?></td>
						</tr>
					</tbody>
				</table>

				<details class="sml-guide-details">
					<summary><?php echo esc_html__('View code examples', 'signocore-multilanguage'); ?></summary>
					<code class="sml-guide-code"><pre>// Get the Danish translation of a post
$translated_id = apply_filters('wpml_object_id', $post_id, 'post', true, 'da');

// Get the current language
$current_lang = apply_filters('wpml_current_language', null);

// Get all active languages
$languages = apply_filters('wpml_active_languages', null);</pre></code>
				</details>
			</div>
		</div>
		<?php
	}
}
