@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()) :: :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 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, Oban.Job.t()} | {:error, Ecto.Changeset.t()}

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

• {:ok, %Oban.Job{}} - Job was successfully enqueued
• {:error, changeset} - Failed to enqueue job