> ## Documentation Index
> Fetch the complete documentation index at: https://developers.octaviatech.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Translate a form into one or more languages

> Translates a form's multilingual text, section titles/descriptions, field labels/placeholders and option labels. The source language is detected from the form unless `sourceLanguage` is provided. Every flag in `fields` defaults to true, so an empty `fields` object translates the whole form. A target language that already holds a translation and no explicit `sourceLanguage` fails with 400 rather than overwriting.



## OpenAPI

````yaml /api-reference/ai-cms/openapi-TAGTEST.json post /ai/translateForm
openapi: 3.1.0
info:
  title: Blog API
  version: 1.0.0
servers:
  - url: https://api.octaviatech.app/cms
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: Tags
    description: Tag management endpoints
paths:
  /ai/translateForm:
    post:
      tags:
        - AI Automation
      summary: Translate a form into one or more languages
      description: >-
        Translates a form's multilingual text, section titles/descriptions,
        field labels/placeholders and option labels. The source language is
        detected from the form unless `sourceLanguage` is provided. Every flag
        in `fields` defaults to true, so an empty `fields` object translates the
        whole form. A target language that already holds a translation and no
        explicit `sourceLanguage` fails with 400 rather than overwriting.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - formId
                - targetLanguages
              properties:
                formId:
                  type: string
                  example: '{{objectId}}'
                targetLanguages:
                  type: array
                  minItems: 1
                  items:
                    type: string
                  description: Target language codes; at least one is required
                  example:
                    - en
                    - ar
                    - tr
                sourceLanguage:
                  type: string
                  description: Source language; auto-detected from the form when omitted
                  example: en
                fields:
                  type: object
                  additionalProperties: false
                  description: >-
                    Which parts of the form to translate. All flags default to
                    true.
                  properties:
                    title:
                      type: boolean
                      default: true
                    description:
                      type: boolean
                      default: true
                    submitButtonText:
                      type: boolean
                      default: true
                    sections:
                      type: boolean
                      default: true
                    sectionTitles:
                      type: boolean
                      default: true
                    sectionDescriptions:
                      type: boolean
                      default: true
                    fieldLabels:
                      type: boolean
                      default: true
                    fieldPlaceholders:
                      type: boolean
                      default: true
                    fieldOptions:
                      type: boolean
                      default: true
                      description: >-
                        Translates option labels; option values are never
                        translated
            examples:
              Basic:
                value:
                  formId: '{{objectId}}'
                  targetLanguages:
                    - en
                    - ar
                    - tr
                  sourceLanguage: en
      responses:
        '200':
          description: OK (translated)
          content:
            application/json:
              example:
                success: true
                statusCode: 200
                message: Form translated successfully
                data:
                  formId: '{{objectId}}'
                  sourceLanguage: en
                  targetLanguages:
                    - en
                    - ar
                    - tr
                  translations:
                    en:
                      title: Contact us
                      description: …
                      submitButtonText: Send
                      sections:
                        - index: 0
                          title: Your details
                          description: …
                          fields:
                            - name: email
                              label: Email address
                              placeholder: you@example.com
                              options: []
              schema:
                allOf:
                  - $ref: '#/components/schemas/Envelope'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/AiFormTranslateResult'
        '400':
          description: >-
            Missing formId, empty targetLanguages, undetectable source language,
            or an existing translation without sourceLanguage
        '401':
          description: Unauthorized
        '403':
          description: Forbidden (role not allowed)
        '404':
          description: Form not found for this tenant
        '426':
          description: Upgrade required (ai_tokens limit exceeded)
        '500':
          description: Failed to translate form
      security:
        - ApiKeyAuth: []
components:
  schemas:
    Envelope:
      type: object
      properties:
        success:
          type: boolean
        statusCode:
          type: integer
        message:
          type: string
        data:
          type:
            - object
            - 'null'
      required:
        - success
        - statusCode
        - message
        - data
    AiFormTranslateResult:
      type: object
      properties:
        formId:
          $ref: '#/components/schemas/ObjectId'
        sourceLanguage:
          type: string
        targetLanguages:
          type: array
          items:
            type: string
        translations:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/AiFormSectionTranslation'
    ObjectId:
      type: string
      pattern: ^[a-fA-F0-9]{24}$
    AiFormSectionTranslation:
      type: object
      properties:
        title:
          type: string
        description:
          type: string
        submitButtonText:
          type: string
        sectionTitles:
          type: array
          items:
            type: string
        sectionDescriptions:
          type: array
          items:
            type: string
        fieldLabels:
          type: array
          items:
            type: string
        fieldPlaceholders:
          type: array
          items:
            type: string
        fields:
          type: array
          items:
            $ref: '#/components/schemas/AiFormFieldTranslation'
    AiFormFieldTranslation:
      type: object
      properties:
        label:
          type: string
        placeholder:
          type: string
        options:
          type: array
          items:
            type: object
            properties:
              value:
                type: string
              label:
                type: string
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````