/**
* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
* For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
*/
/**
* @module ai/aitranslate/aitranslategateway
* @publicApi
*/
import { ContextPlugin, type PluginDependenciesOf } from "@ckeditor/ckeditor5-core";
import { AIConnector } from "../aicore/aiconnector.js";
import { AIReviewCoreEditing } from "../aireviewcore/aireviewcoreediting.js";
import type { AIRunResult } from "../aicore/model/airunresult.js";
import type { AICheckRunSingleRootResult } from "../aireviewcore/model/aichecksinglerootresult.js";
import { AIEditing } from "../aicore/aiediting.js";
import { AIGateway, type AIGatewayApplyOptions, type AIRunBaseOptions } from "../aicore/aigateway.js";
import { type AIEditorRoot } from "../aicore/model/aieditorroot.js";
export type AITranslateRunOptions = AIRunBaseOptions & {
	/**
	* The roots to translate. When omitted, every non-`$graveyard` root across every editor in the current
	* `Context` is translated. When provided, only the listed roots are translated; the order of entries in
	* `roots` is treated as a set-membership filter and does not affect the payload order.
	*
	* Each entry's `channelId` must match an editor's `collaboration.channelId`; `rootName` must match a
	* non-`$graveyard` root within that editor.
	*/
	roots?: Array<AIEditorRoot>;
};
/**
* Headless, stateless public API for running AI translations end-to-end.
*
* This plugin can be loaded standalone (without `AITranslate` plugin) to expose a programmatic
* translation API. It is also transparently loaded by `AITranslate` to back the UI-driven flow.
*/
export declare class AITranslateGateway extends ContextPlugin {
	/**
	* @inheritDoc
	*/
	static get pluginName(): "AITranslateGateway";
	/**
	* @inheritDoc
	*/
	static get requires(): PluginDependenciesOf<[AIReviewCoreEditing, AIConnector, AIEditing, AIGateway]>;
	/**
	* @inheritDoc
	*/
	static override get isOfficialPlugin(): true;
	/**
	* @inheritDoc
	*/
	static override get isPremiumPlugin(): true;
	/**
	* Translates every non-`$graveyard` root across every editor in the current `Context` into the given language and
	* returns one {@link module:ai/aireviewcore/model/aichecksinglerootresult~AICheckRunSingleRootResult result} per root. Each
	* result carries its own `channelId` and `rootName`, identifying the editor/root it belongs to.
	*
	* Each per-root result can then be processed independently. To insert or suggest changes back to the editor,
	* pass the full array (or any caller-filtered subset) to {@link #applyTranslate}.
	*
	* Each per-root {@link module:ai/aireviewcore/model/aichecksinglerootresult~AICheckRunSingleRootResult} always resolves —
	* transport, parsing and merge failures are surfaced via `status: 'error'` plus the `error` field, not thrown.
	* Aborts (via `options.signal`) are reported as `status: 'aborted'` on every per-root entry.
	*
	* When the `roots` option is provided, its entries are validated at the call boundary. An entry that does not
	* resolve to a live, non-`$graveyard` root throws `ai-reviewcoreediting-root-not-found`; an empty `roots` array
	* throws `ai-reviewcoreediting-empty-roots`.
	*
	* The target language is not restricted to a predefined list and is forwarded to the translate endpoint as-is.
	* See the {@glink features/ai/ckeditor-ai-translate#supported-languages supported languages} guide.
	*
	* @experimental **Experimental:** This is a production-ready API but may change in minor releases
	* without the standard deprecation policy. Check the changelog for migration guidance.
	* @param language The target language to translate the content into.
	* @param options Optional `roots` filter and `signal` to allow aborting the run.
	*/
	runTranslate(language: string, options?: AITranslateRunOptions): Promise<AIRunResult<AICheckRunSingleRootResult>>;
	/**
	* Applies a translate run result (produced by {@link #runTranslate}) to the editor content, either as direct
	* changes or as track-changes suggestions. Each per-root sub-result is applied to the root identified by its own
	* `channelId` and `rootName`. Pass `options.roots` to restrict the apply to a subset of roots — the filter is
	* symmetric with the one accepted by {@link #runTranslate}.
	*
	* @experimental **Experimental:** This is a production-ready API but may change in minor releases
	* without the standard deprecation policy. Check the changelog for migration guidance.
	* @param result The result returned by {@link #runTranslate}.
	* @param options Apply options forwarded to {@link module:ai/aicore/aigateway~AIGateway#apply}, including the
	* `applyMethod` and an optional `roots` filter.
	*/
	applyTranslate(result: AIRunResult<AICheckRunSingleRootResult>, options: AIGatewayApplyOptions): void;
}