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

> ## Agent Instructions
> Weaverse component configuration uses `settings`. `inspector` is deprecated; never generate it.
> Weaverse Hydrogen themes use React Router v7: import from `react-router`, never `react-router-dom` or `@remix-run/*`.
> Before using any code sample, read `@weaverse/hydrogen` in the project's `package.json`: 6.x and 5.x import from different entries and use different type names, so code for one does not build on the other.
> `@weaverse/hydrogen` 6 (Shopify Hydrogen 2026.10 and later, the version these docs show) imports from `@weaverse/hydrogen/react-router` and uses `Weaverse*` types such as `WeaverseComponentProps`, `WeaverseComponentLoaderArgs` and `WeaverseComponentSchema`; the root `@weaverse/hydrogen` entry only exports `createSchema()`, data helpers and types.
> `@weaverse/hydrogen` 5.x (Hydrogen 2026.4 and earlier) imports everything from `@weaverse/hydrogen` and uses `HydrogenComponentProps`, `ComponentLoaderArgs` and `HydrogenComponentSchema`. On a 5.x project, convert samples to these names. Upgrade to 6 only when asked (`npx @weaverse/cli@latest migrate v6`, plus the Hydrogen 2026.10 upgrade). Do not mix major versions.
> Next.js themes use `@weaverse/hydrogen` 6.2.0 or later: import client and shared code from `@weaverse/hydrogen/next` and server-only code from `@weaverse/hydrogen/next/server`. `@weaverse/next` is deprecated; never install or import it.
> For live project data (pages, theme settings, translations), use the Weaverse MCP server: https://weaverse.io/docs/developer-tools/weaverse-mcp

# Validate or apply a translation batch

> Submits a batch of 1-50 translation units read from `GET /projects/{projectId}/translation-units`. `{operation}` is one of:

- `validate`: runs every check (unit membership, value shape, placeholders, source and target generations, duplicates) and writes nothing. Returns `object: "translation_validation"` with a per-unit `outcome` of `apply` or `unchanged`.
- `apply`: runs the same checks under the project lock, then writes only `Translation` rows, atomically. Returns `object: "translation_apply"` with `applied`/`unchanged` counts and an exact primary `readback` of every submitted unit. The cache is invalidated once; if that fan-out fails the write still stands and the response carries `cacheDelivery: "degraded"`.

Any other `{operation}` value returns 404.

Each unit echoes `id`, `sourceGeneration` and `targetGeneration` exactly as listed (`targetGeneration: null` when no target was stored), plus `translatedValue`:

- Text units take a string (max 20,000 characters). `{{name}}` and `{name}` placeholders in the source must appear unchanged in the translation.
- Image units take `{ url, alt?, width?, height? }`; `url` must be `https://` or root-relative.
- `null` clears the overlay so the source shows through. An empty string is rejected. Clearing an absent target, or re-clearing a cleared one, reports `unchanged`.

Concurrency and atomicity:
- Any stale source or target refuses the whole batch with 409 `STALE_TRANSLATION` (`details.unitId`, `details.side`) and writes nothing. Re-read the inventory and resubmit.
- A unit outside this project's writable content for the locale returns 404 `TRANSLATION_UNIT_NOT_FOUND` (`details.unitId`) and writes nothing.
- A unit whose target already holds the requested value is `unchanged` regardless of the generation it carries, so an identical retry converges.
- On `apply`, every submitted unit (including ones the preflight found unchanged) is re-proven against locked source and target state; a unit that moved between preflight and lock fails the whole batch.
- Under the same lock, `apply` re-proves each unit's stored-schema approval (the field must still be a declared text input, or image input for an image unit, of its component type; otherwise 409) and the target's authority (the locale must still resolve to the same configured, non-default language; otherwise 400 or 409). Nothing is written in either case.

Authentication: accepts shop API keys, scoped API keys and delegated MCP OAuth tokens that hold the scope, and project-bound translation agent tokens (`wv_agent_…`, Authorization header only). Agent tokens are accepted only on the translation-unit routes.

Required scope: `translations:write`



## OpenAPI

````yaml https://studio.weaverse.io/api/v1/content/openapi.json post /projects/{projectId}/translations/{operation}
openapi: 3.1.0
info:
  title: Weaverse Content API
  version: 1.0.0
  description: >-
    Authenticated REST API for reading and editing Weaverse-managed content
    (projects, pages, drafts, global sections, theme settings, languages) and
    for reading and writing per-locale translations.


    ## Authentication


    Send a bearer token in the `Authorization` header: a shop API key
    (`WEAVERSE_API_KEY`), a scoped API key or a delegated MCP OAuth token.
    Translation-unit routes also accept a project-bound translation agent token.
    Each operation's description ends with the scope it requires.


    ## Scopes


    | Scope | Grants |

    |---|---|

    | `content:read` | Read projects, pages, theme settings, versions, drafts
    and translation units |

    | `content:write` | Save drafts and make non-destructive edits (page items,
    metadata, SEO, assignments, languages, glossary). Never publishes or deletes
    |

    | `content:publish` | Publish drafts, schedule, reschedule or cancel
    publications, restore versions, publish global sections |

    | `content:delete` | Delete pages, global sections, languages and static
    keys, and revert overrides. Project deletion also needs `project:manage` |

    | `project:manage` | Create, copy and delete projects; settings, variants,
    hierarchy, backups, restore as new, previews and hostname policy |

    | `translations:read` | Read translation units only, with no general content
    access |

    | `translations:write` | Apply translation units only; never changes page
    content |


    A legacy API key without scopes keeps read, write and translation access and
    every endpoint that existed before scopes, but never gains publish, delete
    or project management.
servers:
  - url: https://studio.weaverse.io/api/v1/content
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Projects
    description: List, read, rename, create, copy and delete projects.
  - name: Pages
    description: List, read, create, update and delete the pages of a project.
  - name: Drafts and publishing
    description: >-
      Edit page drafts, then publish, schedule, restore and manage page
      versions.
  - name: Global sections
    description: Read, edit and publish sections shared across pages.
  - name: Page settings
    description: Read and edit page-level settings such as SEO metadata.
  - name: Assignments
    description: Map Shopify resources and routes to Weaverse pages and templates.
  - name: Theme settings
    description: Read and update a project's theme settings.
  - name: Languages and localization
    description: List project languages and manage locales, static text and glossary.
  - name: Translations
    description: >-
      Read and write per-locale translations, built for external translation
      agents.
  - name: Project structure
    description: Manage project variants and the project hierarchy.
  - name: Backups and portability
    description: Back up, restore, export and import project content.
  - name: Previews and hostnames
    description: Create preview links and manage the hostnames a project accepts.
  - name: Specification
    description: This OpenAPI document.
paths:
  /projects/{projectId}/translations/{operation}:
    summary: '#2873 validate or apply a translation batch (translations:write)'
    description: >-
      validate: every check (membership, value shape, placeholders, source and
      target generations, duplicates), zero writes, per-unit outcome. apply: the
      same checks under the project lock, then writes only Translation rows
      atomically. Any stale source or target refuses the whole batch with
      STALE_TRANSLATION 409 and writes nothing; an identical retry converges to
      unchanged; returns exact primary readback and invalidates once. Every
      submitted unit, including ones the preflight found unchanged, is re-proven
      against locked source and target state; a unit that moved between
      preflight and lock fails the whole batch. Under the same lock apply also
      re-proves each unit's stored-schema approval (the field must still be a
      declared text input, or image input for an image unit, of its component
      type; otherwise 409 and nothing written) and the target's authority (the
      locale must still resolve to the same configured, non-default language;
      otherwise 400/409 and nothing written). translatedValue null clears: an
      absent target stays absent and an existing clear stays a clear, both
      reported unchanged.
    parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
      - name: operation
        in: path
        required: true
        schema:
          type: string
          enum:
            - validate
            - apply
    post:
      tags:
        - Translations
      summary: Validate or apply a translation batch
      description: >-
        Submits a batch of 1-50 translation units read from `GET
        /projects/{projectId}/translation-units`. `{operation}` is one of:


        - `validate`: runs every check (unit membership, value shape,
        placeholders, source and target generations, duplicates) and writes
        nothing. Returns `object: "translation_validation"` with a per-unit
        `outcome` of `apply` or `unchanged`.

        - `apply`: runs the same checks under the project lock, then writes only
        `Translation` rows, atomically. Returns `object: "translation_apply"`
        with `applied`/`unchanged` counts and an exact primary `readback` of
        every submitted unit. The cache is invalidated once; if that fan-out
        fails the write still stands and the response carries `cacheDelivery:
        "degraded"`.


        Any other `{operation}` value returns 404.


        Each unit echoes `id`, `sourceGeneration` and `targetGeneration` exactly
        as listed (`targetGeneration: null` when no target was stored), plus
        `translatedValue`:


        - Text units take a string (max 20,000 characters). `{{name}}` and
        `{name}` placeholders in the source must appear unchanged in the
        translation.

        - Image units take `{ url, alt?, width?, height? }`; `url` must be
        `https://` or root-relative.

        - `null` clears the overlay so the source shows through. An empty string
        is rejected. Clearing an absent target, or re-clearing a cleared one,
        reports `unchanged`.


        Concurrency and atomicity:

        - Any stale source or target refuses the whole batch with 409
        `STALE_TRANSLATION` (`details.unitId`, `details.side`) and writes
        nothing. Re-read the inventory and resubmit.

        - A unit outside this project's writable content for the locale returns
        404 `TRANSLATION_UNIT_NOT_FOUND` (`details.unitId`) and writes nothing.

        - A unit whose target already holds the requested value is `unchanged`
        regardless of the generation it carries, so an identical retry
        converges.

        - On `apply`, every submitted unit (including ones the preflight found
        unchanged) is re-proven against locked source and target state; a unit
        that moved between preflight and lock fails the whole batch.

        - Under the same lock, `apply` re-proves each unit's stored-schema
        approval (the field must still be a declared text input, or image input
        for an image unit, of its component type; otherwise 409) and the
        target's authority (the locale must still resolve to the same
        configured, non-default language; otherwise 400 or 409). Nothing is
        written in either case.


        Authentication: accepts shop API keys, scoped API keys and delegated MCP
        OAuth tokens that hold the scope, and project-bound translation agent
        tokens (`wv_agent_…`, Authorization header only). Agent tokens are
        accepted only on the translation-unit routes.


        Required scope: `translations:write`
      operationId: translationsOperation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TranslationUnitsBatch'
            examples:
              text:
                summary: Translate a text unit
                value:
                  targetLocale: fr-fr
                  units:
                    - id: Y2x6OGszZDJlMDAwOHBvaXU3eXRyNmV3cQBkYXRhLmJ1dHRvblRleHQ
                      sourceGeneration: sha256:i5yxt6P8d6YAZqFxmfpJwVd1EG3A-S_s04MP3XTKlHs
                      targetGeneration: null
                      translatedValue: Acheter maintenant
              image:
                summary: Set a per-locale image
                value:
                  targetLocale: fr-fr
                  units:
                    - id: Y2x6OGszYzlkMDAwN3p4Y3Y4Ym5tMXF3ZQBkYXRhLmltYWdl
                      sourceGeneration: sha256:axHOW2r5Tdlzv_3ImeCIvAI67R7sgUIlyLW9iArkGVY
                      targetGeneration: null
                      translatedValue:
                        url: >-
                          https://cdn.shopify.com/s/files/1/0838/0052/3057/files/summer-hero-fr.jpg
                        alt: Héros d'été
                        width: 1920
                        height: 1080
              clear:
                summary: Clear a translation
                value:
                  targetLocale: fr-fr
                  units:
                    - id: Y2x6OGszYzlkMDAwN3p4Y3Y4Ym5tMXF3ZQBkYXRhLmhlYWRpbmc
                      sourceGeneration: sha256:aNCJfb2kY7k558Hq_scUZeouHvrUoY9eaCam_HIB0hk
                      targetGeneration: sha256:zzj5orBWLJCO5eaC_y6jzBO285hKHUQCL5G_-PIhc3A
                      translatedValue: null
      responses:
        '200':
          description: translation_validation or translation_apply result
          content:
            application/json:
              schema:
                type: object
              example:
                object: translation_apply
                projectId: clz8k2m4n0001qwer7tyu8iop
                targetLocale: fr-fr
                requested: 1
                applied: 1
                unchanged: 0
                readback:
                  - id: Y2x6OGszZDJlMDAwOHBvaXU3eXRyNmV3cQBkYXRhLmJ1dHRvblRleHQ
                    status: applied
                    value: Acheter maintenant
                    generation: sha256:jrrmwDqYx6bx8u4zNin5AXBzTiYGEzO8XIsX0eh8SYQ
        '400':
          description: Invalid batch, value or placeholders (nothing written)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Foreign project or missing scope (INSUFFICIENT_SCOPE)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: >-
            Unknown {operation} (only validate and apply exist), or
            TRANSLATION_UNIT_NOT_FOUND: a unit outside this project (nothing
            written)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: >-
            STALE_TRANSLATION: a source or target changed since read (nothing
            written)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                object: error
                code: STALE_TRANSLATION
                message: >-
                  The target of unit
                  Y2x6OGszZDJlMDAwOHBvaXU3eXRyNmV3cQBkYXRhLmJ1dHRvblRleHQ
                  changed since it was read; nothing was written. Re-read the
                  inventory and retry.
                status: 409
                details:
                  unitId: Y2x6OGszZDJlMDAwOHBvaXU3eXRyNmV3cQBkYXRhLmJ1dHRvblRleHQ
                  side: target
components:
  schemas:
    TranslationUnitsBatch:
      type: object
      required:
        - targetLocale
        - units
      properties:
        targetLocale:
          type: string
        units:
          type: array
          minItems: 1
          maxItems: 50
          items:
            type: object
            required:
              - id
              - sourceGeneration
              - targetGeneration
              - translatedValue
            properties:
              id:
                type: string
              sourceGeneration:
                type: string
              targetGeneration:
                type:
                  - string
                  - 'null'
                description: null = no stored target when read
              translatedValue:
                description: >-
                  null clears the overlay; empty string is rejected. Image units
                  take an object.
                oneOf:
                  - type: string
                  - type: 'null'
                  - type: object
                    required:
                      - url
                    properties:
                      url:
                        type: string
                        description: https:// or root-relative
                      alt:
                        type: string
                      width:
                        type: integer
                      height:
                        type: integer
    Error:
      type: object
      required:
        - object
        - code
        - message
        - status
      properties:
        object:
          type: string
          enum:
            - error
        code:
          type: string
          enum:
            - UNAUTHORIZED
            - FORBIDDEN
            - INSUFFICIENT_SCOPE
            - PROJECT_NOT_FOUND
            - PAGE_NOT_FOUND
            - STALE_PAGE
            - STALE_PROJECT
            - STALE_TRANSLATION
            - TRANSLATION_UNIT_NOT_FOUND
            - SERVICE_UNAVAILABLE
            - CONFLICT
            - PRECONDITION_REQUIRED
            - INVALID_PARAMS
            - INTERNAL_ERROR
        message:
          type: string
        status:
          type: integer
        details:
          description: >-
            Optional machine-readable context, for example the clashing handles
            of a 409 CONFLICT.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: WEAVERSE_API_KEY
      description: >-
        Bearer token: a shop API key (`WEAVERSE_API_KEY`), a scoped API key or a
        delegated MCP OAuth token; translation-unit routes also accept a
        project-bound translation agent token. Each operation lists the scope it
        requires; the scope table is in the API description.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.