@spec add_language_to_post(
  String.t(),
  String.t(),
  String.t(),
  integer() | nil,
  keyword() | map()
) :: {:ok, map()} | {:error, any()}

Adds a new language translation to an existing post.

Accepts an optional version parameter to specify which version to add the translation to. If not specified, defaults to the latest version.

@spec clear_translation(
  String.t(),
  String.t(),
  String.t(),
  pos_integer() | nil,
  keyword() | map()
) :: :ok | {:error, term()}

Hard-deletes a language's content row from a post.

Unlike delete_language (which archives), this permanently removes the content. Refuses to delete the last remaining language.

@spec default_endpoint_uuid() :: String.t() | nil

Resolves the default AI endpoint UUID for publishing translation.

Reads the publishing_translation_endpoint_uuid setting; nil/"" → nil.

@spec default_prompt_exists?() :: boolean()

Whether the publishing default translation prompt exists (by slug).

@spec default_prompt_uuid() :: String.t() | nil

Resolves the default AI prompt UUID for publishing translation.

Prefers the publishing_translation_prompt_uuid setting, then falls back to the prompt with slug translate-publishing-posts. Both the editor and the bulk API use this so they can't drift (the bulk API previously skipped the slug fallback and could enqueue a nil prompt).

@spec delete_language(
  String.t(),
  String.t(),
  String.t(),
  integer() | nil,
  keyword() | map()
) ::
  :ok | {:error, term()}

Deletes a specific language translation from a post.

For versioned posts, specify the version. For unversioned posts, version is ignored. Refuses to delete the last remaining language content.

Returns :ok on success or {:error, reason} on failure.

@spec set_translation_status(
  String.t(),
  String.t(),
  integer(),
  String.t(),
  String.t()
) ::
  :ok | {:error, any()}

Deprecated no-op. Status is now version-level. Use Versions.publish_version/3 instead.

@spec translate_post_to_all_languages(String.t(), String.t(), keyword()) ::
  {:ok, map()} | {:error, term()}

Enqueues an Oban job to translate a post to all enabled languages using AI.

This creates a background job that will:

1. Read the source post in the primary language
2. Translate the content to each target language using the AI module
3. Create or update translation content for each language

Options

• :endpoint_uuid - AI endpoint UUID to use for translation (required if not set in settings)
• :source_language - Source language to translate from (defaults to primary language)
• :target_languages - List of target language codes (defaults to all enabled except source)
• :version - Version number to translate (defaults to latest/published)
• :user_uuid - User UUID for audit trail

Configuration

Set the default AI endpoint for translations:

PhoenixKit.Settings.update_setting("publishing_translation_endpoint_uuid", "endpoint-uuid")

Examples

# Translate to all enabled languages using default endpoint
{:ok, job} = Publishing.translate_post_to_all_languages("docs", "019cce93-...")

# Translate with specific endpoint
{:ok, job} = Publishing.translate_post_to_all_languages("docs", "019cce93-...",
  endpoint_uuid: "endpoint-uuid"
)

# Translate to specific languages only
{:ok, job} = Publishing.translate_post_to_all_languages("docs", "019cce93-...",
  endpoint_uuid: "endpoint-uuid",
  target_languages: ["es", "fr", "de"]
)

Returns

Delegates to PhoenixKitAI's generic pipeline, enqueuing one job per target language (they run in parallel):

• {:ok, %{enqueued: n, conflicts: n, errors: [], in_flight: [lang]}}
• {:error, reason} - malformed params (e.g. missing endpoint/prompt)

@spec translation_prompt_slug() :: String.t()

The slug of the publishing default translation prompt.