> ## Documentation Index
> Fetch the complete documentation index at: https://docs-docflow.textin.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Translate file extraction results

> Languages use ISO 639-1 codes; Chinese is region-qualified as `zh-CN` or `zh-TW`.
Omitting `source_language` or sending an empty string enables automatic source-language detection.
A concrete source language must differ from `target_language`.
Calling this endpoint translates the task and enables translation in the frontend task detail view.
A concurrent request returns a "task is being translated" error.

Common business error codes:
- `1005025065`: task recognition failed and cannot be translated
- `1005025066`: task recognition has not completed
- `1005025067`: task translation is already in progress
- `1005025068`: source and target languages are the same
- `1005025069`: target language is empty or is not a concrete language code


## OpenAPI

````yaml /docflow/en/rest-api/openapi.bundle.yaml post /api/app-api/sip/platform/v2/file/translate
openapi: 3.0.0
info:
  title: DocFlow API
  description: >-
    DocFlow REST API, providing file upload and file processing result retrieval
    capabilities
  version: 2.14.1
servers:
  - url: https://docflow.textin.com
security:
  - ApiId: []
    SecretCode: []
paths:
  /api/app-api/sip/platform/v2/file/translate:
    post:
      summary: Translate file extraction results
      description: >
        Languages use ISO 639-1 codes; Chinese is region-qualified as `zh-CN` or
        `zh-TW`.

        Omitting `source_language` or sending an empty string enables automatic
        source-language detection.

        A concrete source language must differ from `target_language`.

        Calling this endpoint translates the task and enables translation in the
        frontend task detail view.

        A concurrent request returns a "task is being translated" error.


        Common business error codes:

        - `1005025065`: task recognition failed and cannot be translated

        - `1005025066`: task recognition has not completed

        - `1005025067`: task translation is already in progress

        - `1005025068`: source and target languages are the same

        - `1005025069`: target language is empty or is not a concrete language
        code
      operationId: translateFile
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FileTranslateRequest'
            example:
              task_id: '202412190001'
              source_language: ''
              target_language: zh-CN
      responses:
        '200':
          description: >-
            The request has been processed. Check the business code in the
            response for the outcome.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/CodeMessage'
                  - $ref: '#/components/schemas/FileTranslateResult'
components:
  schemas:
    FileTranslateRequest:
      type: object
      required:
        - task_id
        - target_language
      properties:
        task_id:
          type: string
          description: >-
            ID of a task that completed recognition. Send Snowflake IDs as
            strings; do not convert them to JavaScript Number.
          example: '1978297791713619968'
        source_language:
          $ref: '#/components/schemas/TranslateSourceLanguage'
        target_language:
          $ref: '#/components/schemas/TranslateTargetLanguage'
    CodeMessage:
      type: object
      properties:
        code:
          type: integer
          description: Status code
          example: 200
        msg:
          type: string
          description: Status description
      required:
        - code
        - msg
    FileTranslateResult:
      type: object
      properties:
        result:
          type: object
          required:
            - fields
            - tables
            - stamps
            - handwritings
          properties:
            fields:
              type: array
              description: Translated regular fields
              items:
                $ref: '#/components/schemas/CommonFieldTranslate'
            tables:
              type: array
              description: Translated tables
              items:
                $ref: '#/components/schemas/TableDetailTranslate'
            stamps:
              type: array
              description: Translated stamps
              items:
                $ref: '#/components/schemas/StampTranslateResult'
            handwritings:
              type: array
              description: Translated handwriting
              items:
                $ref: '#/components/schemas/HandwritingTranslateResult'
    TranslateSourceLanguage:
      type: string
      description: >-
        Source language as an ISO 639-1 code. Omit it or send an empty string to
        enable automatic detection.
      enum:
        - ''
        - zh-CN
        - zh-TW
        - ja
        - ko
        - en
        - fr
        - pt
        - de
        - it
        - es
        - ru
        - th
        - vi
        - ms
        - id
        - hi
        - bn
        - ar
        - pl
      example: ''
    TranslateTargetLanguage:
      type: string
      description: Required target language as a concrete ISO 639-1 code.
      enum:
        - zh-CN
        - zh-TW
        - ja
        - ko
        - en
        - fr
        - pt
        - de
        - it
        - es
        - ru
        - th
        - vi
        - ms
        - id
        - hi
        - bn
        - ar
        - pl
      example: zh-CN
    CommonFieldTranslate:
      type: object
      properties:
        key:
          type: string
          description: Original field key
          example: invoiceNumber
        translated_key:
          type: string
          nullable: true
          description: Translated field key; normally unused for table cells
        index:
          type: integer
          description: Zero-based index for fields with the same key
          example: 0
        value:
          type: string
          nullable: true
          description: Translated field value
    TableDetailTranslate:
      type: object
      properties:
        table_name:
          type: string
          description: Original table name
        translated_table_name:
          description: Translated table name
          type: string
          nullable: true
        items:
          type: array
          description: >-
            Translated table data. The outer array contains rows and the inner
            array contains cells.
          items:
            type: array
            items:
              $ref: '#/components/schemas/CommonFieldTranslate'
        item_headers:
          type: array
          description: Translated table headers
          items:
            $ref: '#/components/schemas/TableFieldHeadTranslate'
    StampTranslateResult:
      type: object
      properties:
        key:
          type: string
          description: Unique stamp key in the format stamp-${page}-${index}
        page:
          type: integer
          description: Page number
        index:
          type: integer
          description: Zero-based index on the page
        stamp_prefix:
          type: string
          nullable: true
          description: Translated stamp prefix
        type_key:
          type: string
          nullable: true
          description: Translated stamp type key
        type:
          type: string
          nullable: true
          description: Translated stamp type
        color_key:
          type: string
          nullable: true
          description: Translated stamp color key
        color:
          type: string
          nullable: true
          description: Translated stamp color
        stamp_shape_key:
          type: string
          nullable: true
          description: Translated stamp shape key
        stamp_shape:
          type: string
          nullable: true
          description: Translated stamp shape
        value_key:
          type: string
          nullable: true
          description: Translated stamp text key
        value:
          type: string
          nullable: true
          description: Translated stamp text
    HandwritingTranslateResult:
      type: object
      properties:
        key:
          type: string
          description: >-
            Unique handwriting key in the format
            handwriting-${page}-${lineIndex}
        page:
          type: integer
          description: Page number
        index:
          type: integer
          description: Zero-based index on the page
        handwriting_prefix:
          type: string
          nullable: true
          description: Translated handwriting prefix
        text:
          type: string
          nullable: true
          description: Translated handwriting text
    TableFieldHeadTranslate:
      type: object
      properties:
        key:
          type: string
          description: Original header key
        translated_key:
          type: string
          nullable: true
          description: Translated header key
  securitySchemes:
    ApiId:
      type: apiKey
      in: header
      name: x-ti-app-id
    SecretCode:
      type: apiKey
      in: header
      name: x-ti-secret-code

````