Changeset 3764005 for langforge/trunk/includes/class-post-translation.php

Timestamp:

10/25/2026 06:29:16 AM (3 days ago)

Author:

avakodeforge

Message:

Release 1.3.0 (trunk + tag; see readme changelog)

File:

• langforge/trunk/includes/class-post-translation.php (modified) (49 diffs)

langforge/trunk/includes/class-post-translation.php

@@ -13 +13 @@
 require_once __DIR__ . '/class-translation-failures.php';
 require_once __DIR__ . '/class-part-cache.php';
+require_once __DIR__ . '/class-ai-budget-gate.php';
+// The copy of an Elementor tree gets its element IDs there (LANGFORGE_Elementor_Integration::with_fresh_element_ids).
+require_once __DIR__ . '/class-elementor-integration.php';
 
 // IDE hints for autoloaded classes
@@ -88 +91 @@
         add_action('add_meta_boxes', [$this, 'add_meta_boxes']);
         add_action('save_post', [$this, 'save_post_language'], 10, 2);
+        // BUG-LANG-GLOSS-02: the classic editor shows the glossary check at the top right after a save.
+        add_action('admin_notices', [$this, 'maybe_show_glossary_notice']);
 
         // Auto-assign default language to posts missing _lf_language
@@ -141 +146 @@
         $table = $wpdb->prefix . 'langforge_translations';
 
-        $wpdb->delete($table, ['element_id' => $post_id]); // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared, WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching, PluginCheck.Security.DirectDB.UnescapedDBParameter -- own table from $wpdb->prefix; direct query intended.
+        // A post is the pair (type, ID): a term with the same number keeps its translations (BUG-LANG-SEO-03).
+        $wpdb->query($wpdb->prepare( // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared, WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching, PluginCheck.Security.DirectDB.UnescapedDBParameter -- own table from $wpdb->prefix; the condition is a literal from post_row_sql; direct query intended.
+            "DELETE FROM $table WHERE element_id = %d AND " . self::post_row_sql(), // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared, WordPress.DB.PreparedSQL.NotPrepared -- Table name from $wpdb->prefix, value is %-prepared; post_row_sql is a fixed fragment with no input.
+            (int) $post_id
+        ));
 
         // sibling posts' cached translation arrays listed this
@@ -158 +167 @@
             'avl-gutenberg-sidebar',
             LANGFORGE_PLUGIN_URL . 'assets/js/gutenberg-sidebar.js',
-            ['wp-plugins', 'wp-edit-post', 'wp-element', 'wp-components', 'wp-data', 'wp-i18n', 'wp-api-fetch'],
+            ['wp-plugins', 'wp-edit-post', 'wp-element', 'wp-components', 'wp-data', 'wp-notices', 'wp-i18n', 'wp-api-fetch'],
             LANGFORGE_VERSION,
             true
@@ -168 +177 @@
             'ajaxUrl' => admin_url('admin-ajax.php'),
             'nonce' => wp_create_nonce('langforge_admin_nonce'),
+            // BUG-LANG-GLOSS-02: the heading of the notice shown after a save (the same string as the heading of the
+            // Language box, so it has one translation). Lang does not load script translations, so the text goes
+            // over from here, in the language of the admin.
+            'glossaryHeading' => __('Glossary: this translation does not follow the glossary.', 'langforge'),
         ]);
     }
@@ -218 +231 @@
             return null; // untracked, or already the language being viewed
         }
+        if ($this->request_is_short_address_of($post_id)) {
+            return null; // /?p=<id>: the address names no language, the post names its own
+        }
 
         $translation = $this->get_translation($post_id, $current);
@@ -232 +248 @@
             $this->localizing_permalink = false;
         }
+    }
+
+    /**
+ * Is the request being served the numeric address of this very post (/?p=<id>, /?page_id=<id>,
+ * /?attachment_id=<id>) with no language in it?
+ *
+ * The short address of a translation is what WordPress itself publishes for it (wp_get_shortlink,
+ * <link rel="shortlink">). It names no language, so the language of the request is the default one, and
+ * core's redirect_canonical asks get_permalink of the post for the address to send the visitor to:
+ * the remap of localize_permalink_to_current answered the twin in the default language, and a shared
+ * short link of a Spanish page opened the English one (BUG-LANG-SUITE-02). With no language in the
+ * address the language is the post's own, so the post is not remapped. An address that does name a
+ * language (/en/?p=<es id>) is the visitor's choice and is served as it was.
+ *
+ * Only the post the address names is spared: a link to any other post of another language, the
+ * menu of the same page included, is still remapped to the language being viewed.
+ *
+ * @param int $post_id
+ * @return bool
+ */
+    private function request_is_short_address_of($post_id) {
+        $post_id = (int) $post_id;
+        if ($post_id <= 0) {
+            return false;
+        }
+        $named = false;
+        foreach (['p', 'page_id', 'attachment_id'] as $var) {
+            if ((int) get_query_var($var) === $post_id) {
+                $named = true;
+                break;
+            }
+        }
+        return $named && !LANGFORGE_Core::instance()->language_known_from_start();
     }
 
@@ -280 +329 @@
         $hide_default = get_option('langforge_hide_default_language', false);
 
-        // Don't modify URL for default language if hide option is enabled
-        if ($hide_default && $post_lang === $default_lang) {
-            return $permalink;
-        }
-
         // Check if this post is a translation of the Front Page (fix)
         $front_page_id = (int) get_option('page_on_front');
@@ -295 +339 @@
         }
 
+        // Don't modify URL for default language if hide option is enabled. The one page this does not hold for
+        // is the front page: WordPress gives it the address of the site root only while page_on_front is that
+        // very page, and on a page of another language page_on_front is its translation here (the option filter
+        // translate_front_page_id), so the core permalink of the default-language front page is its slug
+        // (/home/), a second address of the home page. Its address is the home of its language: the site root
+        // (BUG-LANG-SEO-01). The same address for hreflang, canonical and the language switcher.
+        if ($hide_default && $post_lang === $default_lang) {
+            return $is_front_page_translation ? LANGFORGE_Core::instance()->get_raw_home_url('/') : $permalink;
+        }
+
         // Always the *unlocalized* site root: on an /es/ page home_url('/')
         // returns `.../es/`, which no default-language permalink starts with —
@@ -300 +354 @@
         // never be applied to any link rendered on a non-default page.
         $home_url = LANGFORGE_Core::instance()->get_raw_home_url('/');
+
+        // Subdomain and domain formats: a post lives on the host of its own language (es.<host>, the
+        // domain mapped to es); the translation of the front page is the home of its language. The host
+        // comes from the one rule of the plugin, LANGFORGE_Core::host_url_for_language, the same that
+        // the switcher and the URL localizer use. The path is the plain permalink: the language is in the host.
+        if ($url_format === 'subdomain' || $url_format === 'domain') {
+            return LANGFORGE_Core::instance()->host_url_for_language($is_front_page_translation ? $home_url : $permalink, $post_lang);
+        }
 
         if ($url_format === 'parameter') {
@@ -639 +701 @@
                 </div>
                 <?php endif; ?>
+
+                <?php
+                // BUG-LANG-GLOSS-02: a translation typed by hand is checked against the glossary; it only warns.
+                if (!$is_original && $source_post_id) {
+                    echo $this->glossary_warnings_box($this->glossary_warnings($post->ID)); // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- escaped in glossary_warnings_inner.
+                }
+                ?>
 
                 <?php
@@ -749 +818 @@
                 </ul>
             </div>
+            <?php
+            /**
+ * Fires in the Language box, after the list of translations.
+ *
+ * Add-ons hang their markup here: the hint of a WooCommerce product, the Live Preview buttons of Lang Forge Pro.
+ * The callbacks print their own (escaped) HTML.
+ *
+ * @param WP_Post $post The post being edited.
+ */
+            do_action('langforge_meta_box_after_translations', $post);
+            ?>
         </div>
 
@@ -994 +1074 @@
         }
         $label = __('Retry AI translation', 'langforge');
-        $why   = LANGFORGE_Translation_Failures::reason_text($failure['code']);
+        $why   = LANGFORGE_Translation_Failures::reason_text($failure['code'], !empty($failure['trial']));
         $title = $compact ? $label . ' — ' . $why : $why;
 
@@ -1039 +1119 @@
                 if ($failure) {
                     // A draft kept after a failed machine translation: still a link to it, with the reason on its mark.
-                    $title .= ' — ' . LANGFORGE_Translation_Failures::reason_text($failure['code']);
+                    $title .= ' — ' . LANGFORGE_Translation_Failures::reason_text($failure['code'], !empty($failure['trial']));
                 }
-                echo wp_kses_post(self::edit_link_html($translations[$code], esc_html(strtoupper($code)) . ($failure ? LANGFORGE_Translation_Failures::mark_html($failure['code'], true) : ''), [
+                echo wp_kses_post(self::edit_link_html($translations[$code], esc_html(strtoupper($code)) . ($failure ? LANGFORGE_Translation_Failures::mark_html($failure['code'], true, !empty($failure['trial'])) : ''), [
                     'class' => 'lf-col-trans lf-col-trans--exists' . ($failure ? ' lf-col-trans--failed' : ''),
                     'title' => $title,
@@ -1052 +1132 @@
                 // Not translated, and it is known why: a mark with the reason, not a link. There is nothing to open;
                 // the create button of the Translations box of the post makes the draft.
-                $why = LANGFORGE_Translation_Failures::reason_text_without_draft($failures[$code]['code']);
-                echo '<span class="lf-col-trans lf-col-trans--failed" title="' . esc_attr($info['native_name'] . ': ' . $why) . '">' . esc_html(strtoupper($code)) . wp_kses_post(LANGFORGE_Translation_Failures::mark_html($failures[$code]['code'])) . '</span>';
+                $why = LANGFORGE_Translation_Failures::reason_text_without_draft($failures[$code]['code'], !empty($failures[$code]['trial']));
+                echo '<span class="lf-col-trans lf-col-trans--failed" title="' . esc_attr($info['native_name'] . ': ' . $why) . '">' . esc_html(strtoupper($code)) . wp_kses_post(LANGFORGE_Translation_Failures::mark_html($failures[$code]['code'], false, !empty($failures[$code]['trial']))) . '</span>';
             } else {
                 $nonce = wp_create_nonce('langforge_admin_nonce');
@@ -1199 +1279 @@
         // WHERE translation_group IN) with one round-trip, halving the preload
         // cost for both preload_visible_translations and preload_menu_translations.
-        // phpcs:disable WordPress.DB.PreparedSQL.InterpolatedNotPrepared -- Table name from $wpdb->prefix; IN list is integer IDs cast via intval.
+        // The table holds posts AND terms under one unique key (element_id, element_type, language_code), so a post
+        // is the pair (type, ID): both sides of the join are post rows, or a post whose number equals the ID of a
+        // translated category would take that category's group (BUG-LANG-SEO-03).
+        // phpcs:disable WordPress.DB.PreparedSQL.InterpolatedNotPrepared, WordPress.DB.PreparedSQL.NotPrepared -- Table name from $wpdb->prefix; IN list is integer IDs cast via intval; post_row_sql is a fixed fragment with no input.
         $all_translations = $wpdb->get_results( // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching, PluginCheck.Security.DirectDB.UnescapedDBParameter -- Custom plugin table; integer IDs cast via intval.
             "SELECT t2.element_id, t2.language_code, t2.translation_group
              FROM $table t2
              INNER JOIN $table t1 ON t1.translation_group = t2.translation_group
-             WHERE t1.element_id IN ($ids_str)"
+             WHERE t1.element_id IN ($ids_str)
+               AND " . self::post_row_sql('t1') . "
+               AND " . self::post_row_sql('t2')
         );
-        // phpcs:enable WordPress.DB.PreparedSQL.InterpolatedNotPrepared
+        // phpcs:enable WordPress.DB.PreparedSQL.InterpolatedNotPrepared, WordPress.DB.PreparedSQL.NotPrepared
 
         if (empty($all_translations)) {
@@ -1301 +1386 @@
         // Get all translations in this group regardless of element_type
         $results = $wpdb->get_results($wpdb->prepare( // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared, WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching, PluginCheck.Security.DirectDB.UnescapedDBParameter -- own table from $wpdb->prefix; direct query intended.
-            "SELECT element_id, language_code FROM $table WHERE translation_group = %d", // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared -- Table name from $wpdb->prefix, value is %-prepared.
+            "SELECT element_id, language_code FROM $table WHERE translation_group = %d AND " . self::post_row_sql(), // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared, WordPress.DB.PreparedSQL.NotPrepared -- Table name from $wpdb->prefix, value is %-prepared; post_row_sql is a fixed fragment with no input.
             $group
         ), ARRAY_A);
@@ -1632 +1717 @@
 
     /**
+ * How a term row of wp_langforge_translations is told from a post row: the element_type of a term is
+ * "tax_<taxonomy>" (LANGFORGE_Taxonomy_Translation), the element_type of a post is its post type.
+ */
+    const TERM_ELEMENT_PREFIX = 'tax_';
+
+    /**
+ * SQL condition: the row is a post's, not a term's.
+ *
+ * The table keeps posts and terms together, and its unique key is (element_id, element_type,
+ * language_code): post 7 and the category with term ID 7 are different elements. Every lookup that
+ * starts from a post ID, and every join of the table on a post ID, has to carry this condition, or it
+ * reads the translations of a term that has the same number (BUG-LANG-SEO-03). It has no "%" and no
+ * backslash, so it can sit inside a string given to $wpdb->prepare.
+ *
+ * @param string $alias Alias of the table in the statement; empty for none.
+ * @return string e.g. "t1.element_type" -> "LEFT(t1.element_type, 4) <> 'tax_'".
+ */
+    public static function post_row_sql($alias = '') {
+        $column = ($alias === '' ? '' : $alias . '.') . 'element_type';
+        return 'LEFT(' . $column . ', ' . strlen(self::TERM_ELEMENT_PREFIX) . ") <> '" . self::TERM_ELEMENT_PREFIX . "'";
+    }
+
+    /**
  * Is this WPML element type a taxonomy term (category, post_tag, a custom
  * taxonomy, "tax_*", a nav menu) rather than a post?
@@ -1646 +1754 @@
     }
 
+    /**
+ * The translation of a term in a language, from the term pairs of Lang (LANGFORGE_Taxonomy_Translation).
+ *
+ * The pairs of terms are kept in wp_langforge_translations under the element_type "tax_<taxonomy>", apart from
+ * the posts (post_row_sql), so the lookup is strictly by taxonomy: the same number under another taxonomy, or a
+ * post with that number, is another element and is never answered (the "wrong translation" the WPML shim once
+ * read from a table that is not told by type).
+ *
+ * @param int $term_id Term ID.
+ * @param string $element_type A taxonomy ("category") or its WPML element type ("tax_category").
+ * @param string|null $language Language code; the current one when empty.
+ * @return int|null The ID of the term in that language, or null when there is none.
+ */
+    public function get_term_translation_id($term_id, $element_type, $language = null) {
+        if (!$language) {
+            $language = LANGFORGE_Core::instance()->get_current_language();
+        }
+        $taxonomy = (strpos($element_type, self::TERM_ELEMENT_PREFIX) === 0)
+            ? substr($element_type, strlen(self::TERM_ELEMENT_PREFIX))
+            : $element_type;
+        if ($taxonomy === '') {
+            return null;
+        }
+        $found = LANGFORGE_Taxonomy_Translation::instance()->get_term_translation((int) $term_id, $taxonomy, $language);
+        return $found ? (int) $found : null;
+    }
+
     public function get_translation_id($element_id, $element_type = 'post', $language = null, $return_original = false) {
         if (!$language) {
             $language = LANGFORGE_Core::instance()->get_current_language();
         }
-        
+
+        // A term is not a post: its pairs are the term pairs, not the group of the post that has its number.
+        // 'post' is the default of the callers and never names a taxonomy: the common case asks nothing.
+        if ($element_type !== 'post' && self::is_term_element_type($element_type)) {
+            $term_translation = $this->get_term_translation_id($element_id, $element_type, $language);
+            if ($term_translation !== null) {
+                return $term_translation;
+            }
+            return $return_original ? $element_id : null;
+        }
+
         $translations = $this->get_translations($element_id);
         
@@ -1732 +1877 @@
         $group2 = $this->get_translation_group($post_id_2);
 
-        if ($group1 && $group2 && $group1 !== $group2) {
+        if ($group1 && $group2 && (int) $group1 === (int) $group2) {
+            // BUG-LANG-CLI-03: already translations of each other. Nothing to write: falling through to the
+            // "no group on either post" branch made a second group and a second row for each post.
+            // The cache drop and the failure log below still run, as after any link.
+        } elseif ($group1 && $group2 && $group1 !== $group2) {
             // Merge groups - update all items in group2 to group1
             $wpdb->update( // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared, WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching, PluginCheck.Security.DirectDB.UnescapedDBParameter -- own table from $wpdb->prefix; direct query intended.
@@ -1969 +2118 @@
     }
 
+    /** Meta key of the map "element ID in the original -> element ID in the copy" of a translation's Elementor tree. */
+    const ELEMENTOR_ID_MAP_META = '_langforge_elementor_id_map';
+
+    /**
+ * The map "ID of an element of $source -> ID of the element at the same place in $copy" for two Elementor trees
+ * of the same shape (the copy is the original with fresh IDs). Trees are decoded `_elementor_data`.
+ *
+ * @param mixed $source Tree of the original.
+ * @param mixed $copy Tree of the copy.
+ * @return array<string,string>
+ */
+    public static function elementor_id_map($source, $copy): array {
+        $map  = [];
+        $walk = function ($from, $to) use (&$walk, &$map) {
+            if (!is_array($from) || !is_array($to)) {
+                return;
+            }
+            foreach ($from as $i => $element) {
+                $twin = $to[$i] ?? null;
+                if (!is_array($element) || !is_array($twin)) {
+                    continue;
+                }
+                if (isset($element['id'], $twin['id']) && is_scalar($element['id']) && is_scalar($twin['id'])) {
+                    $map[(string) $element['id']] = (string) $twin['id'];
+                }
+                $walk($element['elements'] ?? null, $twin['elements'] ?? null);
+            }
+        };
+        $walk($source, $copy);
+        return $map;
+    }
+
+    /**
+ * Write the map of the Elementor element IDs next to the copy of the tree (BUG-LANG-VEDIT-01): the visual
+ * editor names a text by the original's element IDs and finds the element of the translation by this map. Called
+ * wherever the copy of `_elementor_data` is (re)written, so the map is always the one of the tree that is there.
+ *
+ * @param int $translation_id The translation.
+ * @param string|array $source `_elementor_data` of the original, as stored or decoded.
+ * @param string|array $copy `_elementor_data` written to the translation, as stored or decoded.
+ */
+    public static function record_elementor_id_map(int $translation_id, $source, $copy): void {
+        $source = is_string($source) ? json_decode($source, true) : $source;
+        $copy   = is_string($copy) ? json_decode($copy, true) : $copy;
+        $map    = self::elementor_id_map($source, $copy);
+        if ($map) {
+            update_post_meta($translation_id, self::ELEMENTOR_ID_MAP_META, wp_slash(wp_json_encode($map)));
+        } else {
+            delete_post_meta($translation_id, self::ELEMENTOR_ID_MAP_META);
+        }
+    }
+
     /**
  * Create a translation draft of $post_id in $target_lang.
@@ -2017 +2218 @@
         $new_post_data['post_name'] = $original_post->post_name;
         
-        $new_post_id = wp_insert_post($new_post_data);
+        // wp_insert_post takes slashed data (it unslashes what it is given), and get_post hands the text out unslashed: a
+        // backslash of the source (a path, a pattern, LaTeX) is kept only if the data is slashed on the way in.
+        $new_post_id = wp_insert_post(wp_slash($new_post_data));
         
         if (is_wp_error($new_post_id)) {
@@ -2049 +2252 @@
             '_langforge_language', '_langforge_source_snapshot', '_langforge_needs_update',
             '_pingme', '_encloseme',
-            '_elementor_data',
+            '_elementor_data', self::ELEMENTOR_ID_MAP_META,
         ],
         // What belongs to the source page alone (the canonical URL typed in for it, ...). The
@@ -2077 +2280 @@
 
             // Regenerate unique element IDs to prevent duplicates
-            $data = is_string($elementor_data) ? $elementor_data : wp_json_encode($elementor_data, JSON_UNESCAPED_UNICODE);
-            $data = preg_replace_callback('/"id"\s*:\s*"([a-f0-9]+)"/', function () {
-                return '"id":"' . dechex(random_int(0x1000000, 0xFFFFFFF)) . '"';
-            }, $data);
+            $data = LANGFORGE_Elementor_Integration::with_fresh_element_ids($elementor_data);
             update_post_meta($new_post_id, '_elementor_data', wp_slash($data));
             delete_post_meta($new_post_id, '_elementor_element_cache');
+            // The visual editor finds the element of this copy by the original's element ID through this map.
+            self::record_elementor_id_map((int) $new_post_id, $elementor_data, $data);
 
             // Copy Elementor CSS cache settings so styles render
@@ -2177 +2379 @@
 
     /**
+ * The glossary check of a translation as it is saved (BUG-LANG-GLOSS-02).
+ *
+ * The glossary promises that a term has one translation across every translated page, and the machine
+ * translation is told so (get_payload_for_translate). A translation typed by hand was never looked at. This
+ * reads the saved text of a translation (title, excerpt, content, without tags) against the text of its source
+ * and returns one warning for each glossary term the source has and the translation does not follow
+ * (LANGFORGE_Glossary::validate_translation). It only reports: the translation is saved whatever it says.
+ *
+ * Nothing is reported for a post that is not a translation, for a translation that has no text yet, and for one
+ * whose text is still the copy of its source (it is not translated yet: every term would be named).
+ *
+ * @param int $post_id The translation.
+ * @return string
+ */
+    public function glossary_warnings($post_id) {
+        $post_id = (int) $post_id;
+        if ($post_id <= 0 || !class_exists('LANGFORGE_Glossary')) {
+            return [];
+        }
+        $source_id = $this->get_source_post_id($post_id);
+        if ($source_id <= 0) {
+            return [];
+        }
+        $source_lang = LANGFORGE_Core::instance()->get_default_language();
+        $target_lang = (string) get_post_meta($post_id, '_langforge_language', true);
+        if ($target_lang === '' || $target_lang === $source_lang) {
+            return [];
+        }
+        $own    = $this->glossary_text($post_id);
+        $source = $this->glossary_text($source_id);
+        if ($own === '' || $own === $source) {
+            return [];
+        }
+        return LANGFORGE_Glossary::instance()->validate_translation($source, $own, $source_lang, $target_lang);
+    }
+
+    /**
+ * The words of a post for the glossary check: title, excerpt and content, tags stripped and entities read as the
+ * characters they stand for (the block editor stores "Fish & Chips" as "Fish &amp; Chips", the glossary term is
+ * typed with "&": without this a term with a sign of that kind is never found or is reported as missing).
+ */
+    private function glossary_text($post_id) {
+        $post = get_post((int) $post_id);
+        if (!is_object($post)) {
+            return '';
+        }
+        $parts = [];
+        foreach (['post_title', 'post_excerpt', 'post_content'] as $field) {
+            $text = isset($post->$field) ? trim(html_entity_decode(wp_strip_all_tags((string) $post->$field), ENT_QUOTES | ENT_HTML5, 'UTF-8')) : '';
+            if ($text !== '') {
+                $parts[] = $text;
+            }
+        }
+        return implode("\n", $parts);
+    }
+
+    /** The heading and the list of the warnings (escaped), for the box of the Language metabox and for the notice. */
+    private function glossary_warnings_inner(array $warnings) {
+        $items = '';
+        foreach ($warnings as $warning) {
+            $items .= '<li>' . esc_html($warning) . '</li>';
+        }
+        return '<p style="margin:0;"><strong>' . esc_html__('Glossary: this translation does not follow the glossary.', 'langforge') . '</strong></p>'
+            . '<ul style="margin:6px 0 0 18px;list-style:disc;">' . $items . '</ul>';
+    }
+
+    /** The warning box inside the Language metabox. Empty when there is nothing to say. */
+    private function glossary_warnings_box(array $warnings) {
+        if (!$warnings) {
+            return '';
+        }
+        return '<div class="lf-glossary-warning" role="alert" style="margin:8px 0;padding:8px 10px;border-left:4px solid #dba617;background:#fff8e5;">'
+            . $this->glossary_warnings_inner($warnings) . '</div>';
+    }
+
+    /**
+ * admin_notices: in the classic editor, the glossary check of the translation just saved, at the top of the
+ * screen. The block editor does not reload and does not read the Language box again after a save: there, the
+ * script of the sidebar (assets/js/gutenberg-sidebar.js) reads the REST field `langforge_glossary_warnings` of the
+ * saved post and shows the same list as a notice of the editor.
+ */
+    public function maybe_show_glossary_notice() {
+        if (!function_exists('get_current_screen')) {
+            return;
+        }
+        $screen = get_current_screen();
+        if (!is_object($screen) || $screen->base !== 'post') {
+            return;
+        }
+        if (method_exists($screen, 'is_block_editor') && $screen->is_block_editor()) {
+            return;
+        }
+        // phpcs:disable WordPress.Security.NonceVerification.Recommended -- read-only: whether the screen was reached by a save.
+        if (!isset($_GET['message'], $_GET['post'])) {
+            return;
+        }
+        $post_id = absint(wp_unslash($_GET['post']));
+        // phpcs:enable WordPress.Security.NonceVerification.Recommended
+        if ($post_id <= 0 || !current_user_can('edit_post', $post_id)) {
+            return;
+        }
+        $warnings = $this->glossary_warnings($post_id);
+        if (!$warnings) {
+            return;
+        }
+        echo '<div class="notice notice-warning">' . $this->glossary_warnings_inner($warnings) . '</div>'; // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- escaped in glossary_warnings_inner.
+    }
+
+    /**
  * PUBLIC API — listener for do_action('langforge/translate_post', int $post_id, array $context).
  *
@@ -2246 +2557 @@
         }
 
-        $queued = 0;
+        // One reading of the clock for the whole run: the step between two events is the stagger and nothing
+        // else, however long creating a draft takes (a clock read per event made it one second longer
+        // whenever the run crossed a second).
+        $run_started = time();
+        $queued      = 0;
         foreach (array_keys((array) $core->get_active_languages()) as $target_lang) {
             $target_lang = (string) $target_lang;
@@ -2263 +2578 @@
             }
 
-            if ($this->queue_machine_translation($post_id, (int) $target_id, $source_lang, $target_lang, $queued)) {
+            if ($this->queue_machine_translation($post_id, (int) $target_id, $source_lang, $target_lang, $queued, $run_started)) {
                 // The job may throw this draft away if it cannot translate it, but only while the draft is still as it is now.
                 LANGFORGE_Translation_Failures::stamp_stub((int) $target_id);
@@ -2288 +2603 @@
  * @param string $target_lang
  * @param int $index Position in this run, used for the stagger.
+ * @param int $run_started Time the run began (Unix); the stagger counts from it. 0 = now.
  * @return bool Whether an event was scheduled.
  */
-    protected function queue_machine_translation($source_id, $target_id, $source_lang, $target_lang, $index = 0) {
+    protected function queue_machine_translation($source_id, $target_id, $source_lang, $target_lang, $index = 0, $run_started = 0) {
         $source_id   = (int) $source_id;
         $target_id   = (int) $target_id;
@@ -2309 +2625 @@
         }
 
-        $timestamp = time() + self::MT_QUEUE_DELAY + ($index * self::MT_QUEUE_STAGGER);
+        $timestamp = ((int) $run_started > 0 ? (int) $run_started : time()) + self::MT_QUEUE_DELAY + ($index * self::MT_QUEUE_STAGGER);
 
         $scheduled = wp_schedule_single_event(
@@ -2654 +2970 @@
     /** The answer of the handler when the credits ran out: the one the button turns into the checkout offer. */
     private static function refuse_exhausted_credits($result, $created_id = 0) {
+        $err_data = $result->get_error_data();
         if ($created_id) {
-            LANGFORGE_Translation_Failures::flag_created($created_id, LANGFORGE_Translation_Failures::CODE_CREDITS);
-        }
-        $err_data = $result->get_error_data();
+            LANGFORGE_Translation_Failures::flag_created($created_id, LANGFORGE_Translation_Failures::CODE_CREDITS, is_array($err_data) ? $err_data : null);
+        }
         wp_send_json_error([
             'message'    => $result->get_error_message(),
             'error'      => 'credits_exhausted',
+            // A free trial that cannot pay is told so (the screen does not say "your account has no credits" to it).
+            'trial'      => !empty($err_data['trial']),
             'remaining'  => $err_data['remaining'] ?? 0,
             'reset_date' => $err_data['reset_date'] ?? '',
@@ -2679 +2997 @@
     }
 
+    /**
+ * The parts a body is translated in: one for a short body (the request it always was), the pieces the cutter of the
+ * AI button makes of a long one (LANGFORGE_Forge_API::split_content_for_translation: at the end of a block, a line, a
+ * row or a sentence), and what stood between two pieces (the translated pieces are put together with it). A client of
+ * the service without the cutter (an older Pro add-on whose copy of it is loaded) gets the body whole, as before.
+ *
+ * @return array|WP_Error ['parts' => string, 'glue' => string], or the error of a body that has no place to cut.
+ */
+    private static function content_parts($content) {
+        if (class_exists('LANGFORGE_Forge_API') && is_callable(['LANGFORGE_Forge_API', 'split_content_for_translation'])) {
+            $glue  = [];
+            $parts = LANGFORGE_Forge_API::split_content_for_translation($content, $glue);
+            if (is_wp_error($parts)) {
+                return $parts;
+            }
+            if (is_array($parts) && $parts) {
+                return ['parts' => array_values($parts), 'glue' => is_array($glue) ? array_values($glue) : []];
+            }
+        }
+        return ['parts' => [(string) $content], 'glue' => []];
+    }
+
+    /** The translated parts of a body put together the way the body was written (one line break where the cutter knows no glue). */
+    private static function join_content_parts(array $pieces, array $glue) {
+        $out = '';
+        foreach (array_values($pieces) as $i => $piece) {
+            if ($i > 0) {
+                $out .= isset($glue[$i - 1]) ? $glue[$i - 1] : "\n";
+            }
+            $out .= trim((string) $piece);
+        }
+        return $out;
+    }
+
+    /**
+ * Whether the comments of the blocks of the editor are not the same in the text that came back as in the source: the
+ * number of <!-- wp:name --> and of <!-- /wp:name --> must be (a body that lost one would be a page the editor cannot open).
+ */
+    private static function block_comments_differ($source, $translated) {
+        foreach (['<!-- wp:', '<!-- /wp:'] as $comment) {
+            if (substr_count((string) $source, $comment) !== substr_count((string) $translated, $comment)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    /** The seconds a request of the AI may take before PHP gives up on the script (the client waits 90 seconds for the service). */
+    const AI_REQUEST_TIME_LIMIT = 120;
+
+    /**
+ * Before every request of the AI: the time limit of the script starts again. A long post is a dozen requests one after
+ * the other in the same call, and the limit of a host (30 seconds is usual) would stop it in the middle of the job.
+ */
+    protected function extend_time_limit() {
+        if (!function_exists('set_time_limit')) {
+            return;
+        }
+        $disabled = array_map('trim', explode(',', (string) $this->php_disabled_functions()));
+        if (in_array('set_time_limit', $disabled, true)) {
+            return;
+        }
+        $this->set_php_time_limit(self::AI_REQUEST_TIME_LIMIT);
+    }
+
+    /** The functions the host switched off (a seam: the setting cannot be changed in a running script). */
+    protected function php_disabled_functions() {
+        return ini_get('disable_functions');
+    }
+
+    /** set_time_limit (a seam). */
+    protected function set_php_time_limit($seconds) {
+        // phpcs:ignore Squiz.PHP.DiscouragedFunctions.Discouraged -- a long translation is many requests in one call; checked for availability above
+        @set_time_limit($seconds);
+    }
+
     /** What the person is told when no text came back: the reason of the service if there is one. */
     private static function ai_failure_message($ai_error) {
@@ -2692 +3086 @@
     }
 
+    /**
+ * A refusal of run_ai_translation: the WP_Error a caller reads, and the answer the button makes of it.
+ *
+ * @param array|null $ajax What the button answers (wp_send_json_error): ['message' => $message] when null.
+ * @param int|null $status The HTTP status the button answers with (null: the default one).
+ * @param array|null $credits What the service has charged for this run so far (see credits_since); null: none known.
+ */
+    private static function run_refusal($code, $message, $ajax = null, $status = null, $credits = null) {
+        $data = ['ajax' => $ajax !== null ? $ajax : ['message' => $message]];
+        if ($status !== null) {
+            $data['status'] = $status;
+        }
+        if ($credits !== null) {
+            $data['credits'] = $credits;
+        }
+        return new WP_Error($code, $message, $data);
+    }
+
+    /** An error that was made before (a refusal of a caller's check, of the service) with what the run has charged added to its data. */
+    private static function with_credits(WP_Error $error, $credits) {
+        if ($credits === null) {
+            return $error;
+        }
+        $data = $error->get_error_data();
+        $data = is_array($data) ? $data : [];
+        $data['credits'] = $credits;
+        return new WP_Error($error->get_error_code(), $error->get_error_message(), $data);
+    }
+
+    /** The AI client's running count of what the service charged (null when the client keeps none). */
+    private static function credits_snapshot($ai) {
+        if (!method_exists($ai, 'credits_report')) {
+            return null;
+        }
+        $report = $ai->credits_report();
+        return is_array($report) ? $report : null;
+    }
+
+    /**
+ * What the service has charged for the calls since $before: ['charged' => int|null, 'remaining' => int|null].
+ * 'charged' is null when a call of the run came back without the figure (it was made and its price is not known).
+ */
+    private static function credits_since($ai, $before) {
+        $after = $before === null ? null : self::credits_snapshot($ai);
+        if ($after === null) {
+            return null;
+        }
+        $uncounted = (int) ($after['uncounted'] ?? 0) - (int) ($before['uncounted'] ?? 0);
+        return [
+            'charged'   => $uncounted > 0 ? null : max(0, (int) ($after['charged'] ?? 0) - (int) ($before['charged'] ?? 0)),
+            'remaining' => isset($after['remaining']) && is_numeric($after['remaining']) ? (int) $after['remaining'] : null,
+        ];
+    }
+
+    /** The error of a text the service refused for lack of credits, or that came back without its shortcodes: null for any other answer. */
+    private static function part_error($result, $created_id, $credits) {
+        if (!is_wp_error($result)) {
+            return null;
+        }
+        $code = $result->get_error_code();
+        if ($code === 'credits_exhausted') {
+            $err_data = $result->get_error_data();
+            if ($created_id) {
+                LANGFORGE_Translation_Failures::flag_created($created_id, LANGFORGE_Translation_Failures::CODE_CREDITS, is_array($err_data) ? $err_data : null);
+            }
+            return self::with_credits($result, $credits);
+        }
+        // The code as a string: the add-on's copy of the client (which has the constant) may not be the one that is loaded.
+        if ($code === 'langforge_ai_shortcodes_lost') {
+            if ($created_id) {
+                LANGFORGE_Translation_Failures::flag_created($created_id, LANGFORGE_Translation_Failures::CODE_SHORTCODES);
+            }
+            return self::with_credits($result, $credits);
+        }
+        return null;
+    }
+
+    /** What the button sends when run_ai_translation refused: the answer it always sent for that refusal. */
+    private static function answer_run_refusal(WP_Error $error) {
+        if ($error->get_error_code() === 'credits_exhausted') {
+            // The page "Create + AI translate" made was flagged by the run; the button only sends the answer.
+            self::refuse_exhausted_credits($error, 0);
+        }
+        self::refuse_lost_shortcodes($error, 0);
+        $data   = $error->get_error_data();
+        $ajax   = is_array($data) && isset($data['ajax']) && is_array($data['ajax']) ? $data['ajax'] : ['message' => $error->get_error_message()];
+        $status = is_array($data) && isset($data['status']) ? (int) $data['status'] : null;
+        if ($status !== null) {
+            wp_send_json_error($ajax, $status);
+        }
+        wp_send_json_error($ajax);
+    }
+
+    /**
+ * The AI Translate button. The nonce, the rights and the reading of the request are its own; the translation is
+ * run_ai_translation, the one core every caller translates a post by.
+ */
     public function ajax_ai_translate_post() {
         check_ajax_referer('langforge_admin_nonce', 'nonce');
@@ -2703 +3194 @@
         }
 
-        // The second step of "Create + AI translate" says so (admin.js). The button then leaves for the edit screen of
+        $source_lang = sanitize_text_field(wp_unslash($_POST['source_lang'] ?? ''));
+        $target_lang = sanitize_text_field(wp_unslash($_POST['target_lang'] ?? ''));
+
+        // The second step of "Create + AI translate" says so (admin.js): the run flags the page it made, so that
+        // whatever failed is told on its edit screen (see run_ai_translation).
+        $result = $this->run_ai_translation($source_id, $target_lang, [
+            'target_id'    => $target_id,
+            'source_lang'  => $source_lang,
+            'after_create' => !empty($_POST['after_create']),
+        ]);
+        if (is_wp_error($result)) {
+            self::answer_run_refusal($result);
+            return;
+        }
+
+        wp_send_json_success([
+            /* translators: %d: number of fields that were translated. */
+            'message'    => sprintf(_n('Translated %d field successfully.', 'Translated %d fields successfully.', (int) $result['translated_count'], 'langforge'), (int) $result['translated_count']),
+            'target_id'  => $result['target_id'],
+            'edit_url'   => $result['edit_url'],
+        ]);
+    }
+
+    /**
+ * Translates a post with the AI of Lang Forge into a translation of it: the title, the content and the excerpt
+ * one request each, the meta of the post in one batch, the fields of Field Forge, the descriptions of the
+ * variations of a WooCommerce product, the SEO meta; with the glossary and the model of the site, the shortcodes
+ * kept out of the AI's hands, and what came back kept for an hour (LANGFORGE_Part_Cache) so that a second try pays
+ * only for what failed. This is what the AI button of the Translations box does (ajax_ai_translate_post), and
+ * nothing else translates a post differently.
+ *
+ * Rights are the caller's: the method checks none (like create_translation).
+ *
+ * @param int $source_id The post to translate from.
+ * @param string $target_lang The language to translate into.
+ * @param array $opts {
+ * @type int $target_id The translation to write into. Without it the translation the post has in that
+ * language is used.
+ * @type string $source_lang The language of the source (default: the language of the post).
+ * @type string $mode 'write' (default: as the button, whatever the status of the translation is) or
+ * 'draft_only': no translation makes a draft (after the texts came back, so that
+ * a refusal leaves nothing behind), a draft or a pending translation is
+ * updated, any other status is refused before the AI is asked for anything.
+ * @type bool $after_create The translation is the page "Create + AI translate" has just made: a failure
+ * is flagged on it, so that its edit screen says why it is not translated.
+ * @type callable $verify_before_write function (int $target_id): true|WP_Error, called after the texts came back and
+ * before anything is written (the caller's last look; 0 when nothing exists yet).
+ * @type int $max_credits The most the run may spend (default: no limit, as the button runs). Before every
+ * request (a text, a custom field, a field of Field Forge, a description of a variation,
+ * an SEO field) the run checks that what the service has charged so far plus the table
+ * price of that request stays within it; when it does not, nothing more is asked, what
+ * came back is written, and the answer says which parts were left (see below).
+ * A request that is dearer than the table says (a very long text) cannot be known
+ * beforehand: the one after it is not started.
+ * @type int $part_credits The table price of one request (default 1, the price of the action `translate`).
+ * }
+ * @return array|WP_Error ['target_id', 'translated_count', 'edit_url', 'created', 'credits' => ['charged', 'remaining']
+ * (only from a client that counts), and when max_credits stopped the run 'stopped_at_budget' => true and
+ * 'untranslated' => the parts that were left (title, content, excerpt, custom_fields, field_forge_fields,
+ * variation_descriptions, seo_title, seo_description)]; or the error (langforge_ai_over_budget: not even the
+ * first request fits, nothing was asked or written). The error's data may hold 'ajax' (what the
+ * button answers), 'status', and 'credits' (what the service has charged for the run, when the
+ * AI was already asked). credits_exhausted and langforge_ai_shortcodes_lost are the errors of the
+ * client, as they came.
+ */
+    public function run_ai_translation(int $source_id, string $target_lang, array $opts = []) {
+        $draft_only = isset($opts['mode']) && $opts['mode'] === 'draft_only';
+        $target_id  = isset($opts['target_id']) ? (int) $opts['target_id'] : 0;
+
+        // The second step of "Create + AI translate" says so. The button then leaves for the edit screen of
         // the page it made, and whatever failed must be told there, once, from here: the screen reads the flag, not the
         // address (LANGFORGE_Translation_Failures::render_created_notice). Until a good answer takes the flag back,
@@ -2709 +3269 @@
         // with no answer at all (a fatal error, a timeout) too; a refusal that knows its reason replaces it. The AI
         // button of a page that already exists does not ask: its person stays on the screen and reads the toast.
-        $created_id = !empty($_POST['after_create']) ? $target_id : 0;
+        $created_id = !empty($opts['after_create']) ? $target_id : 0;
         if ($created_id) {
             LANGFORGE_Translation_Failures::flag_created($created_id, LANGFORGE_Translation_Failures::CREATED_OTHER);
@@ -2717 +3277 @@
         // class is absent — return a clean error rather than fataling.
         if (!class_exists('LANGFORGE_AI_Client')) {
-            wp_send_json_error(['message' => __('AI translation requires the Lang Forge Pro add-on.', 'langforge')]);
+            return self::run_refusal('langforge_ai_unavailable', __('AI translation requires the Lang Forge Pro add-on.', 'langforge'));
         }
         $ai = LANGFORGE_AI_Client::instance();
         if (!$ai->is_configured()) {
-            wp_send_json_error(['message' => __('AI translation not configured. Go to Lang Forge → Settings.', 'langforge')]);
+            return self::run_refusal('langforge_ai_not_configured', __('AI translation not configured. Go to Lang Forge → Settings.', 'langforge'));
         }
         // Enforce it server-side too. is_configured only proves a key is
@@ -2728 +3288 @@
         // AI credits. The add-on reports the feature off on Free / expired plans.
         if (!LANGFORGE_Pro_Bridge::instance()->is_enabled('ai_translation')) {
-            wp_send_json_error(['message' => __('AI translation is not enabled in Lang Forge Pro on this site.', 'langforge')], 403);
-        }
-
-        $source_lang = sanitize_text_field(wp_unslash($_POST['source_lang'] ?? ''));
-        $target_lang = sanitize_text_field(wp_unslash($_POST['target_lang'] ?? ''));
+            return self::run_refusal('langforge_ai_disabled', __('AI translation is not enabled in Lang Forge Pro on this site.', 'langforge'), null, 403);
+        }
+
+        $source_lang = array_key_exists('source_lang', $opts) ? (string) $opts['source_lang'] : (string) $this->get_post_language($source_id);
 
         if (!$source_lang || !$target_lang) {
-            wp_send_json_error(['message' => __('Missing required parameters.', 'langforge')]);
+            return self::run_refusal('langforge_ai_missing_params', __('Missing required parameters.', 'langforge'));
         }
 
         $source = get_post($source_id);
-        $target = get_post($target_id);
-        if (!$source || !$target) {
-            wp_send_json_error(['message' => __('Post not found.', 'langforge')]);
-        }
+        if ($target_id <= 0 && $source) {
+            // A caller that names no translation means the one the post has (and the button always names one).
+            $target_id = $draft_only ? (int) $this->get_translation($source_id, $target_lang) : 0;
+            if ($target_id <= 0 && !$draft_only) {
+                return self::run_refusal('langforge_ai_no_target', 'The post has no translation to write into in this language: name it with the option target_id.');
+            }
+        }
+        $target = $target_id > 0 ? get_post($target_id) : null;
+        if (!$source || ($target_id > 0 && !$target)) {
+            if ($draft_only && $source) {
+                return self::run_refusal('langforge_ai_target_missing', sprintf('Lang Forge links post %d to a translation (post %d) that no longer exists.', $source_id, $target_id));
+            }
+            return self::run_refusal('langforge_ai_post_not_found', __('Post not found.', 'langforge'));
+        }
+
+        if ($draft_only) {
+            // A draft is all this mode writes into, and it is known before the AI is asked: a refusal here costs nothing.
+            $refusal = $this->draft_only_refusal($source_id, $source, $target, $target_id, $target_lang, false);
+            if ($refusal === null && trim((string) $source->post_title) === '' && trim((string) $source->post_content) === '' && trim((string) $source->post_excerpt) === '') {
+                $refusal = new WP_Error('langforge_ai_nothing_to_translate', sprintf('Post %d has no title, body or excerpt to translate.', $source_id));
+            }
+            if ($refusal !== null) {
+                return $refusal;
+            }
+        }
+
+        // The body is cut before the first request: a body with no place to cut cannot go out whole (the service would cut the
+        // answer at 4096 tokens and say nothing), and the refusal costs nothing, not even the title.
+        $body = !empty($source->post_content) ? self::content_parts($source->post_content) : ['parts' => [], 'glue' => []];
+        if (is_wp_error($body)) {
+            return self::run_refusal($body->get_error_code(), $body->get_error_message());
+        }
+
+        // What the service charges for this run is what the client counts from here (null: it keeps no count).
+        $credits_before = self::credits_snapshot($ai);
+        $credits_now    = function () use ($ai, $credits_before) {
+            return self::credits_since($ai, $credits_before);
+        };
+
+        // With a budget every request below goes through the gate (it stands in for the client from here on); without one
+        // the AI client is asked directly, as it always was. What the service charged is still read from the client itself
+        // ($credits_now above holds it).
+        $gate = null;
+        if (array_key_exists('max_credits', $opts) && $opts['max_credits'] !== null) {
+            $gate = new LANGFORGE_AI_Budget_Gate($ai, (int) $opts['max_credits'], isset($opts['part_credits']) ? (int) $opts['part_credits'] : 1, $credits_before);
+            $ai   = $gate;
+        }
+        $begin = function ($part) use ($gate) {
+            if ($gate !== null) {
+                $gate->begin($part);
+            }
+        };
+        // A request of the AI starts the time limit of the script again (a long post is a dozen of them in one call).
+        $extend = function () {
+            $this->extend_time_limit();
+        };
 
         $translated_count = 0;
@@ -2750 +3361 @@
         // The three texts are translated first and written afterwards. A text in which the AI lost or changed a
         // shortcode comes back as the error LANGFORGE_Forge_API::SHORTCODES_LOST, and that refuses the whole
-        // translation (self::refuse_lost_shortcodes): a title in the language of the translation over a content
+        // translation (self::part_error): a title in the language of the translation over a content
         // that is not, or a green "Translated 1 fields successfully" about a page whose form or gallery is broken,
         // would be worse than telling the person and leaving the translation as it was.
@@ -2759 +3370 @@
         // request are dropped when the page is written: a person who translates it again wants a new one.
         $cache_keys = [];
-        $translate_part = function ($kind, $text, $context) use ($ai, $source_lang, $target_lang, &$cache_keys) {
+        $last_key = null;
+        $translate_part = function ($kind, $text, $context) use ($ai, $source_lang, $target_lang, &$cache_keys, &$last_key, $extend) {
+            $last_key = null;
             if (trim((string) $text) === '') {
                 return $ai->translate($text, $source_lang, $target_lang, $context);
@@ -2773 +3386 @@
             $key   = LANGFORGE_Part_Cache::key($kind, $source_lang, $target_lang, $text, [$model, $glossary]);
             $cache_keys[] = $key;
+            $last_key     = $key;
             $kept = LANGFORGE_Part_Cache::get($key);
             if (is_string($kept) && trim($kept) !== '') {
                 return $kept;
             }
+            $extend();
             $translated = $ai->translate($text, $source_lang, $target_lang, $context);
             if (is_string($translated) && trim($translated) !== '') {
@@ -2784 +3399 @@
         };
 
+        // A request the budget refused is a stop, not a failure: the part stays as it is (null here), the parts after it
+        // are asked in their turn (the gate refuses them too, and a part kept from an earlier try is still free).
         // Translate title
+        $begin(LANGFORGE_AI_Budget_Gate::PART_TITLE);
         $title_result = $translate_part('title', $source->post_title, 'page/post title');
-        if (is_wp_error($title_result) && $title_result->get_error_code() === 'credits_exhausted') {
-            self::refuse_exhausted_credits($title_result, $created_id);
-        }
-        self::refuse_lost_shortcodes($title_result, $created_id);
+        $title_held   = LANGFORGE_AI_Budget_Gate::is_denial($title_result);
+        if ($title_held) {
+            $title_result = null;
+        }
+        if (($refused = self::part_error($title_result, $created_id, $credits_now())) !== null) {
+            return $refused;
+        }
 
         // A part that went out and did not come back whole (an error, nothing, blanks) ends the request: the page
         // cannot be written half translated, and the texts after it are not paid for.
-        $broken = self::ai_part_failed($source->post_title, $title_result) ? $title_result : null;
-
-        // Translate content
+        $broken = !$title_held && self::ai_part_failed($source->post_title, $title_result) ? $title_result : null;
+
+        // Translate content. A long body goes out in parts (the service answers with 4096 tokens at most and does not say
+        // when it stopped there, so a long text in one request would come back cut and look like a success), every part
+        // one request through the same gate; the body is one field of the translation: it is written when all its parts
+        // are here, and never half. The parts that did come back are in the cache of the parts for an hour.
         $content_result = null;
+        // How many parts of the body came back, and of how many (the body of one part is the request it always was).
+        $content_came  = 0;
+        $content_total = 0;
+        // The cache keys of the parts of the body, and of those whose own block comments came back changed.
+        $content_keys = [];
+        $lost_keys    = [];
         if ($broken === null && !empty($source->post_content)) {
-            $content_result = $translate_part('content', $source->post_content, 'blog post/page content with HTML');
-            if (is_wp_error($content_result) && $content_result->get_error_code() === 'credits_exhausted') {
-                self::refuse_exhausted_credits($content_result, $created_id);
-            }
-            self::refuse_lost_shortcodes($content_result, $created_id);
-            $broken = self::ai_part_failed($source->post_content, $content_result) ? $content_result : null;
+            $begin(LANGFORGE_AI_Budget_Gate::PART_CONTENT);
+            $content_parts = $body['parts'];
+            $content_total = count($content_parts);
+            if ($content_total < 2) {
+                $content_result = $translate_part('content', $source->post_content, 'blog post/page content with HTML');
+                $content_keys[] = $last_key;
+                $content_held   = LANGFORGE_AI_Budget_Gate::is_denial($content_result);
+                if ($content_held) {
+                    $content_result = null;
+                }
+                if (($refused = self::part_error($content_result, $created_id, $credits_now())) !== null) {
+                    return $refused;
+                }
+                $broken = !$content_held && self::ai_part_failed($source->post_content, $content_result) ? $content_result : null;
+            } else {
+                $pieces = [];
+                foreach ($content_parts as $i => $content_part) {
+                    $piece = $translate_part('chunk', $content_part, sprintf('HTML content part %d of %d. Preserve all HTML tags.', $i + 1, $content_total));
+                    $content_keys[] = $last_key;
+                    if (LANGFORGE_AI_Budget_Gate::is_denial($piece)) {
+                        break;
+                    }
+                    if (($refused = self::part_error($piece, $created_id, $credits_now())) !== null) {
+                        return $refused;
+                    }
+                    if (self::ai_part_failed($content_part, $piece)) {
+                        // The parts after it are not paid for.
+                        $broken = $piece === null ? '' : $piece;
+                        break;
+                    }
+                    if (self::block_comments_differ($content_part, $piece)) {
+                        $lost_keys[] = $last_key;
+                    }
+                    $pieces[] = $piece;
+                }
+                $content_came = count($pieces);
+                if ($content_came === $content_total) {
+                    $content_result = self::join_content_parts($pieces, $body['glue']);
+                }
+            }
+            // A body that came back with another number of block comments than it went out with is not written: the editor
+            // cannot open such a page. What came back stays in the cache of the parts, so that a second try pays only for the
+            // texts that are missing, and the texts after the body are not asked.
+            if (is_string($content_result) && trim($content_result) !== '' && self::block_comments_differ($source->post_content, $content_result)) {
+                // The parts whose comments changed are asked again by a second try (an answer kept would fail the same way for an
+                // hour); the others are kept. When no single part changed (a comment moved to the next one), none is trusted.
+                LANGFORGE_Part_Cache::forget(array_filter($lost_keys ? $lost_keys : $content_keys));
+                $message = __('The translation of this post was not saved: the number of block comments of the editor in it does not match the original. What came back is kept for an hour, so a second try pays only for what still has to be translated. Try again, or translate this post by hand.', 'langforge');
+                return self::run_refusal('langforge_ai_blocks_lost', $message, ['message' => $message, 'error' => 'blocks_lost'], null, $credits_now());
+            }
         }
 
@@ -2809 +3483 @@
         $excerpt_result = null;
         if ($broken === null && !empty($source->post_excerpt)) {
+            $begin(LANGFORGE_AI_Budget_Gate::PART_EXCERPT);
             $excerpt_result = $translate_part('excerpt', $source->post_excerpt, 'post excerpt/summary');
-            if (is_wp_error($excerpt_result) && $excerpt_result->get_error_code() === 'credits_exhausted') {
-                self::refuse_exhausted_credits($excerpt_result, $created_id);
-            }
-            self::refuse_lost_shortcodes($excerpt_result, $created_id);
-            $broken = self::ai_part_failed($source->post_excerpt, $excerpt_result) ? $excerpt_result : null;
+            $excerpt_held   = LANGFORGE_AI_Budget_Gate::is_denial($excerpt_result);
+            if ($excerpt_held) {
+                $excerpt_result = null;
+            }
+            if (($refused = self::part_error($excerpt_result, $created_id, $credits_now())) !== null) {
+                return $refused;
+            }
+            $broken = !$excerpt_held && self::ai_part_failed($source->post_excerpt, $excerpt_result) ? $excerpt_result : null;
         }
 
@@ -2821 +3499 @@
             // reason of the service, as before. Either way nothing is written - not the title that did come back,
             // not the snapshot of the source, and the failure record of the language stays (the Retry button).
-            $came_back = false;
+            $came_back = $content_came > 0;
             foreach ([$title_result, $content_result, $excerpt_result] as $result) {
                 if (is_string($result) && trim($result) !== '') {
@@ -2828 +3506 @@
             }
             if ($came_back) {
-                wp_send_json_error([
-                    'message' => LANGFORGE_Translation_Failures::reason_text(LANGFORGE_Translation_Failures::CODE_PARTIAL),
+                $message = LANGFORGE_Translation_Failures::reason_text(LANGFORGE_Translation_Failures::CODE_PARTIAL);
+                return self::run_refusal(LANGFORGE_Translation_Failures::CODE_PARTIAL, $message, [
+                    'message' => $message,
                     'error'   => LANGFORGE_Translation_Failures::CODE_PARTIAL,
-                ]);
-            }
-            wp_send_json_error(['message' => self::ai_failure_message($broken)]);
+                ], null, $credits_now());
+            }
+            return self::run_refusal('langforge_ai_failed', self::ai_failure_message($broken), null, null, $credits_now());
+        }
+
+        // The budget did not even cover the first request (no request went out, so nothing came back and nothing is
+        // owed): there is nothing to write, and no draft is made for it.
+        if ($gate !== null && $gate->stopped()) {
+            $any_text = false;
+            foreach ([$title_result, $content_result, $excerpt_result] as $result) {
+                if (is_string($result) && trim($result) !== '') {
+                    $any_text = true;
+                }
+            }
+            if (!$any_text) {
+                // A body that stopped between its parts (a post with nothing but a body) has been paid for in part: the parts
+                // that came back are kept, nothing is written, and the one who asks again pays for the rest only.
+                $message = $content_came > 0
+                    ? sprintf('The budget of this translation (max_credits %d) ended inside the body: %d of its %d parts came back and are kept for an hour, so that a second try pays only for the rest. Nothing was written.', (int) $opts['max_credits'], $content_came, $content_total)
+                    : sprintf('The first request of this translation does not fit in max_credits (%d): the AI was not asked and nothing was written.', (int) $opts['max_credits']);
+                return self::run_refusal(LANGFORGE_AI_Budget_Gate::DENIED, $message, null, null, $credits_now());
+            }
+        }
+
+        // A draft is all draft_only writes into, and the world may have changed while the service worked: the
+        // translation may have been published, and the caller's own rights may have gone. The texts are paid for; a
+        // refusal here writes nothing, and says what the run has charged.
+        if ($draft_only && $target_id > 0) {
+            clean_post_cache($target_id);
+            $now     = get_post($target_id);
+            $refusal = $now
+                ? $this->draft_only_refusal($source_id, $source, $now, $target_id, $target_lang, true)
+                : new WP_Error('langforge_ai_target_missing', sprintf('The %s translation (post %d) is gone. It disappeared while the AI was translating; nothing was written.', $target_lang, $target_id));
+            if ($refusal !== null) {
+                return self::with_credits($refusal, $credits_now());
+            }
+        }
+        if (isset($opts['verify_before_write']) && is_callable($opts['verify_before_write'])) {
+            $verdict = call_user_func($opts['verify_before_write'], $target_id);
+            if (is_wp_error($verdict)) {
+                return self::with_credits($verdict, $credits_now());
+            }
+        }
+
+        // The draft of a language that has none is made now, when what goes into it is in hand.
+        $created = false;
+        if ($draft_only && $target_id <= 0) {
+            $made = $this->create_translation($source_id, $target_lang);
+            if (is_wp_error($made)) {
+                return self::with_credits($made, $credits_now());
+            }
+            $target_id = (int) $made;
+            $created   = true;
         }
 
         // Nothing was refused: write what came through.
         if (is_string($title_result) && trim($title_result) !== '') {
-            wp_update_post(['ID' => $target_id, 'post_title' => $title_result]);
+            // wp_update_post takes slashed data (it unslashes what it is given): a text is slashed first, or each backslash
+            // of the translation (a path, a pattern, LaTeX) is eaten.
+            wp_update_post(['ID' => $target_id, 'post_title' => wp_slash($title_result)]);
             $translated_count++;
         }
 
         if (is_string($content_result) && trim($content_result) !== '') {
-            wp_update_post(['ID' => $target_id, 'post_content' => $content_result]);
+            wp_update_post(['ID' => $target_id, 'post_content' => wp_slash($content_result)]);
             $translated_count++;
         }
 
         if (is_string($excerpt_result) && trim($excerpt_result) !== '') {
-            wp_update_post(['ID' => $target_id, 'post_excerpt' => $excerpt_result]);
+            wp_update_post(['ID' => $target_id, 'post_excerpt' => wp_slash($excerpt_result)]);
             $translated_count++;
         }
 
-        // The three texts are in the page: what was kept for a second try is spent.
-        LANGFORGE_Part_Cache::forget($cache_keys);
+        // The three texts are in the page: what was kept for a second try is spent. (A run that stopped at its budget keeps
+        // them: the try with a higher budget pays only for what is left.)
+        if ($gate === null || !$gate->stopped()) {
+            LANGFORGE_Part_Cache::forget($cache_keys);
+        }
 
         // Translate ALL text postmeta in ONE batch API call
@@ -2896 +3630 @@
                 $segments[] = ['key' => $key, 'text' => $val];
             }
+            $begin(LANGFORGE_AI_Budget_Gate::PART_FIELDS);
+            $extend();
             $bulk_result = $ai->translate_bulk($segments, $source_lang, $target_lang);
             if (!is_wp_error($bulk_result) && is_array($bulk_result)) {
                 foreach ($bulk_result as $key => $translated_val) {
                     if (!empty($translated_val)) {
-                        update_post_meta($target_id, $key, $translated_val);
+                        // update_post_meta unslashes the value it is given: slashed here, the backslashes survive.
+                        update_post_meta($target_id, $key, wp_slash($translated_val));
                         $translated_count++;
                     }
@@ -2910 +3647 @@
         // the translation says in its own words (the variations themselves are made when the translation is).
         if (class_exists('LANGFORGE_WooCommerce_Variations')) {
+            $begin(LANGFORGE_AI_Budget_Gate::PART_VARIATIONS);
+            $extend();
             $translated_count += LANGFORGE_WooCommerce_Variations::instance()->translate_descriptions($source_id, $target_id, $ai, $source_lang, $target_lang);
         }
@@ -2929 +3668 @@
         $ff_exists = $wpdb->get_var($wpdb->prepare('SHOW TABLES LIKE %s', $ff_table)) === $ff_table; // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- related Forge table existence check
         if ($ff_exists) {
+            // The table of Field Forge is written with $wpdb, which takes the text as it is: no slashing here.
+            $begin(LANGFORGE_AI_Budget_Gate::PART_FF_FIELDS);
+            $extend();
             $translated_count += $this->translate_fieldforge_values(
                 $ff_table, $source_id, $target_id, $ai, $source_lang, $target_lang
@@ -2937 +3679 @@
         $seo_title = get_post_meta($source_id, '_rankforge_meta_title', true);
         if ($seo_title) {
+            $begin(LANGFORGE_AI_Budget_Gate::PART_SEO_TITLE);
+            $extend();
             $seo_title_t = $ai->translate($seo_title, $source_lang, $target_lang, 'SEO meta title');
-            if (!is_wp_error($seo_title_t)) update_post_meta($target_id, '_rankforge_meta_title', $seo_title_t);
+            if (!is_wp_error($seo_title_t)) update_post_meta($target_id, '_rankforge_meta_title', wp_slash($seo_title_t));
         }
         $seo_desc = get_post_meta($source_id, '_rankforge_meta_description', true);
         if ($seo_desc) {
+            $begin(LANGFORGE_AI_Budget_Gate::PART_SEO_DESC);
+            $extend();
             $seo_desc_t = $ai->translate($seo_desc, $source_lang, $target_lang, 'SEO meta description');
-            if (!is_wp_error($seo_desc_t)) update_post_meta($target_id, '_rankforge_meta_description', $seo_desc_t);
+            if (!is_wp_error($seo_desc_t)) update_post_meta($target_id, '_rankforge_meta_description', wp_slash($seo_desc_t));
         }
 
@@ -2951 +3697 @@
         // Translation Status "Out of Date" tile/list. Without this, the
         // user re-translates and the row still shows up flagged.
-        if ($translated_count > 0) {
+        // A run that stopped at its budget leaves parts untranslated: the translation is not in sync with the source,
+        // so the snapshot is not taken and the flag stays.
+        $stopped = $gate !== null && $gate->stopped();
+        if ($translated_count > 0 && !$stopped) {
             $fresh_source = get_post($source_id);
             if ($fresh_source) {
-                update_post_meta($target_id, '_langforge_source_snapshot', [
+                // The array goes through update_post_meta too, which unslashes every string in it.
+                update_post_meta($target_id, '_langforge_source_snapshot', wp_slash([
                     'title'   => (string) $fresh_source->post_title,
                     'content' => (string) $fresh_source->post_content,
-                ]);
+                ]));
             }
             delete_post_meta($target_id, '_langforge_needs_update');
@@ -2965 +3715 @@
 
         if ($translated_count === 0) {
-            wp_send_json_error(['message' => self::ai_failure_message(null)]);
-        }
-
-        if ($created_id) {
+            return self::run_refusal('langforge_ai_failed', self::ai_failure_message(null), null, null, $credits_now());
+        }
+
+        if ($created_id && !$stopped) {
             LANGFORGE_Translation_Failures::unflag_created($created_id);
         }
 
-        wp_send_json_success([
-            /* translators: %d: number of fields that were translated. */
-            'message'    => sprintf(__('Translated %d fields successfully.', 'langforge'), $translated_count),
-            'target_id'  => $target_id,
-            'edit_url'   => self::edit_url($target_id, 'raw'),
-        ]);
+        $done = [
+            'target_id'        => $target_id,
+            'translated_count' => $translated_count,
+            'edit_url'         => self::edit_url($target_id, 'raw'),
+            'created'          => $created,
+        ];
+        if ($stopped) {
+            $done['stopped_at_budget'] = true;
+            $done['untranslated']      = $gate->untranslated();
+        }
+        $credits = $credits_now();
+        if ($credits !== null) {
+            $done['credits'] = $credits;
+        }
+        return $done;
+    }
+
+    /**
+ * Why draft_only does not write into this translation (null: it may). The record must be a translation of this post
+ * (the same kind of post, kept in this language), and of any status but draft and pending it is live or on its way to
+ * be (published, private, scheduled), or gone (trash, auto-draft).
+ *
+ * @param object|null $target The translation as it is read now (null: the language has none).
+ */
+    private function draft_only_refusal($source_id, $source, $target, $target_id, $target_lang, $after_the_call) {
+        if ($target === null) {
+            return null;
+        }
+        $kept_in = (string) $this->get_post_language($target_id);
+        if ((string) $target->post_type !== (string) $source->post_type || $kept_in !== $target_lang) {
+            return new WP_Error('langforge_ai_target_mismatch', sprintf(
+                'Post %d is linked as the %s translation of post %d, but it is a %s kept in "%s". The link looks broken: check it in the Lang Forge box of the post. Nothing was written.',
+                $target_id,
+                $target_lang,
+                $source_id,
+                (string) $target->post_type,
+                $kept_in
+            ));
+        }
+        if (!in_array((string) $target->post_status, ['draft', 'pending'], true)) {
+            return new WP_Error('langforge_ai_target_live', sprintf(
+                'The %s translation (post %d) is %s, and this mode writes into a draft or a pending translation only.%s',
+                $target_lang,
+                $target_id,
+                (string) $target->post_status,
+                $after_the_call ? ' It changed while the AI was translating; nothing was written.' : ''
+            ));
+        }
+        return null;
     }
 }