<?php
if (!defined('ABSPATH')) {
  exit;
}

/**
 * Detect whether the separate PHP JSON extension is available.
 */
$awxct_has_php_json_extension = false;
if ( class_exists( 'AWXCT_Features' ) && method_exists( 'AWXCT_Features', 'has_json_php' ) ) {
  $awxct_has_php_json_extension = AWXCT_Features::has_json_php();
}
?>

<div class="awxct-wrap" style="max-width: 900px;">

  <?php if ( ! $awxct_has_php_json_extension ) : ?>
    <div class="notice notice-warning">
      <p>
        <?php esc_html_e(
          'This feature is available via a separate extension for PHP-based JSON translation loading.',
          'anywarex-clone-translate'
        ); ?>
      </p>
    </div>
  <?php endif; ?>

  <h1>AnyWareX Clone Translate – PHP Translation Guide</h1>

  <p>
    <?php esc_html_e(
      'AnyWareX Clone Translate supports structured JSON files for server-side translations in PHP. These files are stored in the wp-content/uploads/anywarex-clone-translate/i18n/php/ directory, one file per locale.',
      'anywarex-clone-translate'
    ); ?>
  </p>

  <p>
    <?php esc_html_e(
      'Prepared example JSON files shipped with the extension are located in the plugin folder under /i18n/php/ (or /assets/i18n/php/ depending on the package). You can copy/adapt them into wp-content/uploads/anywarex-clone-translate/i18n/php/.',
      'anywarex-clone-translate'
    ); ?>
  </p>

  <div style="background:#f8f8f8;border-left:4px solid #999;padding:12px;margin:20px 0;">
    <strong><?php esc_html_e('Prepared example files:', 'anywarex-clone-translate'); ?></strong><br>
    <?php esc_html_e(
      'In the /i18n/php/ folder you will find example files named like xx-xx-example.json (for example de-de-example.json).',
      'anywarex-clone-translate'
    ); ?>
    <?php esc_html_e(
      'To use an example file, rename it to xx-xx.json (for example de-de.json).',
      'anywarex-clone-translate'
    ); ?>
    <?php esc_html_e(
      'The -example suffix prevents your translation files from being overwritten when updating the plugin.',
      'anywarex-clone-translate'
    ); ?>
  </div>

  <hr>

  <h2><?php esc_html_e('1. Example JSON file (PHP)', 'anywarex-clone-translate'); ?></h2>

  <p><?php esc_html_e('A JSON translation file for PHP typically looks like this:', 'anywarex-clone-translate'); ?></p>

<pre><code>{
  "services": {
    "web": "Sviluppo Web",
    "cloud": "Servizi di Migrazione Cloud",
    "security": "Audit di Cybersecurity"
  }
}
</code></pre>

  <p><?php esc_html_e('JSON files are stored at:', 'anywarex-clone-translate'); ?></p>

<pre><code>/wp-content/uploads/anywarex-clone-translate/i18n/php/{locale}.json</code></pre>

  <p><?php esc_html_e('Example:', 'anywarex-clone-translate'); ?></p>

<pre><code>/wp-content/uploads/anywarex-clone-translate/i18n/php/it-it.json</code></pre>

  <hr>

  <h2><?php esc_html_e('2. Accessing JSON values via PHP', 'anywarex-clone-translate'); ?></h2>

  <div style="background:#fff4d6;border-left:4px solid #f0b400;padding:12px;margin:20px 0;">
    <strong><?php esc_html_e('Separate extension required:', 'anywarex-clone-translate'); ?></strong><br>
    <?php esc_html_e(
      'The function awxct_get_json_value() is available via a separate AnyWareX Clone Translate extension.',
      'anywarex-clone-translate'
    ); ?>
  </div>

  <p>
    <?php esc_html_e(
      'To retrieve a translated value from the JSON file in PHP, use:',
      'anywarex-clone-translate'
    ); ?>
  </p>

<pre><code>&lt;?php echo esc_html( awxct_get_json_value( $loc, 'services.web', 'Web Development' ) ); ?&gt;</code></pre>

  <p>
    <?php esc_html_e(
      'The function reads the currently loaded locale file and returns the translation for the given key path.',
      'anywarex-clone-translate'
    ); ?>
  </p>

  <hr>

  <h2><?php esc_html_e('2.1 Important: Safe usage when the plugin is disabled', 'anywarex-clone-translate'); ?></h2>

  <div style="background:#ffecec;border-left:4px solid #d63638;padding:12px;margin:20px 0;">
    <strong><?php esc_html_e('Prevent fatal errors in your theme:', 'anywarex-clone-translate'); ?></strong><br>
    <?php esc_html_e(
      'If the plugin is deactivated, the function awxct_get_json_value() does not exist. Any direct call in your theme will cause a fatal PHP error (white/black screen).',
      'anywarex-clone-translate'
    ); ?>
  </div>

  <p>
    <?php esc_html_e(
      'Therefore, always wrap calls with function_exists() or use a small helper function in your theme that falls back to the default text when the plugin is not active.',
      'anywarex-clone-translate'
    ); ?>
  </p>

  <p><strong><?php esc_html_e('Option A (recommended): function_exists() check', 'anywarex-clone-translate'); ?></strong></p>

<pre><code>&lt;?php
$label = 'Services';
if ( function_exists('awxct_get_json_value') ) {
  $label = awxct_get_json_value( $loc, 'meta.nav.headings.services', 'Services' );
}
echo esc_html( $label );
?&gt;</code></pre>

  <p><strong><?php esc_html_e('Option B: Add a small wrapper helper to your theme', 'anywarex-clone-translate'); ?></strong></p>

<pre><code>&lt;?php
// In your theme (e.g. functions.php) or in a small mu-plugin.
if ( ! function_exists('awxct_json') ) {
  function awxct_json( $loc, $key, $fallback = '' ) {
    if ( function_exists('awxct_get_json_value') ) {
      return awxct_get_json_value( $loc, $key, $fallback );
    }
    return $fallback;
  }
}

// Usage:
echo esc_html( awxct_json( $loc, 'meta.nav.headings.services', 'Services' ) );
?&gt;</code></pre>

  <p>
    <?php esc_html_e(
      'This makes your theme robust: it will work normally with the separate extension active, and it will still render readable fallback labels if the plugin is disabled.',
      'anywarex-clone-translate'
    ); ?>
  </p>

  <hr>

  <h2><?php esc_html_e('3. Function parameters', 'anywarex-clone-translate'); ?></h2>

  <ul>
    <li><strong>$loc</strong> – <?php esc_html_e('Locale code (e.g. de-de, it-it). In most themes this is a variable like $loc or $locale.', 'anywarex-clone-translate'); ?></li>
    <li><strong>$key</strong> – <?php esc_html_e('Dot notation key path (e.g. services.web or meta.nav.headings.services).', 'anywarex-clone-translate'); ?></li>
    <li><strong>$fallback</strong> – <?php esc_html_e('Fallback string if the key is missing or the locale file does not exist.', 'anywarex-clone-translate'); ?></li>
  </ul>

  <hr>

  <h2><?php esc_html_e('4. Example (nested keys)', 'anywarex-clone-translate'); ?></h2>

  <p><?php esc_html_e('Example JSON:', 'anywarex-clone-translate'); ?></p>

<pre><code>{
  "meta": {
    "nav": {
      "headings": {
        "services": "Services"
      }
    }
  }
}
</code></pre>

  <p><?php esc_html_e('PHP lookup example:', 'anywarex-clone-translate'); ?></p>

<pre><code>$label = awxct_get_json_value(
  $loc,
  'meta.nav.headings.services',
  'Services'
);
</code></pre>

  <hr>

  <h2><?php esc_html_e('5. Directory structure', 'anywarex-clone-translate'); ?></h2>

<pre><code>/wp-content/uploads/anywarex-clone-translate/i18n/php/
 ├── en-us.json
 ├── de-de.json
 ├── it-it.json
 └── fr-fr.json
</code></pre>

  <p><?php esc_html_e('Each JSON file contains all translations for a single language.', 'anywarex-clone-translate'); ?></p>

  <hr>

  <h2><?php esc_html_e('6. Fallback logic', 'anywarex-clone-translate'); ?></h2>

  <p><?php esc_html_e('If a translation key is missing:', 'anywarex-clone-translate'); ?></p>

  <ul>
    <li><?php esc_html_e('Return the key path as-is.', 'anywarex-clone-translate'); ?></li>
    <li><?php esc_html_e('If missing, try the default language file (usually en-us).', 'anywarex-clone-translate'); ?></li>
  </ul>

  <hr>

  <h2><?php esc_html_e('7. Tips', 'anywarex-clone-translate'); ?></h2>

  <ul>
    <li><?php esc_html_e('Keep your JSON structure clean and consistent.', 'anywarex-clone-translate'); ?></li>
    <li><?php esc_html_e('Use lowercase filenames (e.g. de-de.json).', 'anywarex-clone-translate'); ?></li>
    <li><?php esc_html_e('Keep keys consistent between locales.', 'anywarex-clone-translate'); ?></li>
    <li><?php esc_html_e('Use dot notation for nested values.', 'anywarex-clone-translate'); ?></li>
    <li><?php esc_html_e('Avoid spaces in keys.', 'anywarex-clone-translate'); ?></li>
    <li><?php esc_html_e('Ensure UTF-8 encoding (without BOM).', 'anywarex-clone-translate'); ?></li>
    <li><?php esc_html_e('Keep JS and PHP translation files aligned.', 'anywarex-clone-translate'); ?></li>
  </ul>

  <hr>

  <p>
    <?php esc_html_e(
      'This page describes how to create and use PHP-based JSON translations in AnyWareX Clone Translate with the separate PHP extension.',
      'anywarex-clone-translate'
    ); ?>
  </p>

</div>
