> ## 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/*`. > Define component schemas with `createSchema()` from `@weaverse/hydrogen` (React Router themes) or `@weaverse/next` (Next.js themes). > These docs cover @weaverse/hydrogen, @weaverse/react and @weaverse/core 5.x, and @weaverse/next 1.x. Do not use APIs from other major versions. > For live project data (pages, theme settings, translations), use the Weaverse MCP server: https://docs.weaverse.io/developer-tools/weaverse-mcp # List translation units for a target locale > Project-wide translation inventory for one target locale: every unit an agent may translate, with opaque ids, source and target generations, context, storefront usages and a status summary. This is the first step of the translation-unit workflow: 1. `GET /translation-units?targetLocale=…` (optionally `status=missing,stale`) and page with `after=` while `hasMore` is `true`. 2. `POST /translations/validate` with the units you translated: every check runs, nothing is written, and each unit reports `apply` or `unchanged`. 3. `POST /translations/apply` with the same body: the checks re-run under the project lock and the batch is written atomically (compare-and-set on both generations). 4. Use the `readback` in the apply response, or list again, to confirm. What is listed: - Units of the pages the target locale actually renders, resolved with the storefront cascade. Items shared by several pages (global sections) appear once, with every route in `usages`. - Only fields the stored project schema approves: text, richtext and textarea inputs and their defaults. Components without a stored schema, and fields of other input types, are never listed or writable. - `kind=text` (default) lists text units; `kind=image` lists per-locale image overrides at declared image inputs, on the same protocol with an image object as the value. - `summary` counts `current`, `missing` and `stale` across all units of the requested kind (before the `status` filter), plus `excluded`: pages the locale renders that this project cannot write (inherited from a parent project or shared with another project). - A target is `missing` when no row exists or it was cleared, and `stale` when the stored translation answers a source that has since changed. - `usages` lists only concrete storefront paths and may be empty for templates, articles and system pages. Paths use the default route prefixes; a custom page prefix configured in Studio is not reflected. Behaviour: - Ordering is deterministic (by unit id). `limit` is 1-100 (default 100); `after` is a strict lower bound, so a cursor naming a unit that has since disappeared still resumes correctly. - `status` accepts a comma-separated list or repeated parameters. - `targetLocale` must be a configured, non-default language (400 otherwise). - Uncached by design: it carries the generations a write compare-and-sets against. 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 by this route and `POST /translations/{operation}`; a token bound to another project gets 403. Required scope: `translations:read` ## OpenAPI ````yaml https://studio.weaverse.io/api/v1/content/openapi.json get /projects/{projectId}/translation-units openapi: 3.1.0 info: title: Weaverse Content API version: 1.0.0 description: >- Authenticated REST API for querying Weaverse-managed content (projects, pages, theme settings, languages) and for reading and writing per-locale translations. 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}/translation-units: summary: '#2873 translation-unit inventory (translations:read)' description: >- Every unit the stored project schema approves (text/richtext/textarea inputs and their defaults; image units only at declared image inputs) — components without a stored schema, or fields of other input types, are never listed or writable — of the pages the target locale renders, with opaque ids, source/target generations, context, usages and a current/missing/stale/excluded summary. kind=image lists per-locale image overrides on the same protocol. Uncached. Also the only read admitting project-bound translation agent tokens. Writes: POST /projects/{projectId}/translations/validate and /translations/apply. parameters: - name: projectId in: path required: true schema: type: string - name: targetLocale in: query required: true schema: type: string - name: kind in: query schema: type: string enum: - text - image default: text - name: status in: query description: Comma-separated or repeated schema: type: array items: type: string enum: - current - missing - stale - name: limit in: query schema: type: integer minimum: 1 maximum: 100 - name: after in: query schema: type: string get: tags: - Translations summary: List translation units for a target locale description: >- Project-wide translation inventory for one target locale: every unit an agent may translate, with opaque ids, source and target generations, context, storefront usages and a status summary. This is the first step of the translation-unit workflow: 1. `GET /translation-units?targetLocale=…` (optionally `status=missing,stale`) and page with `after=` while `hasMore` is `true`. 2. `POST /translations/validate` with the units you translated: every check runs, nothing is written, and each unit reports `apply` or `unchanged`. 3. `POST /translations/apply` with the same body: the checks re-run under the project lock and the batch is written atomically (compare-and-set on both generations). 4. Use the `readback` in the apply response, or list again, to confirm. What is listed: - Units of the pages the target locale actually renders, resolved with the storefront cascade. Items shared by several pages (global sections) appear once, with every route in `usages`. - Only fields the stored project schema approves: text, richtext and textarea inputs and their defaults. Components without a stored schema, and fields of other input types, are never listed or writable. - `kind=text` (default) lists text units; `kind=image` lists per-locale image overrides at declared image inputs, on the same protocol with an image object as the value. - `summary` counts `current`, `missing` and `stale` across all units of the requested kind (before the `status` filter), plus `excluded`: pages the locale renders that this project cannot write (inherited from a parent project or shared with another project). - A target is `missing` when no row exists or it was cleared, and `stale` when the stored translation answers a source that has since changed. - `usages` lists only concrete storefront paths and may be empty for templates, articles and system pages. Paths use the default route prefixes; a custom page prefix configured in Studio is not reflected. Behaviour: - Ordering is deterministic (by unit id). `limit` is 1-100 (default 100); `after` is a strict lower bound, so a cursor naming a unit that has since disappeared still resumes correctly. - `status` accepts a comma-separated list or repeated parameters. - `targetLocale` must be a configured, non-default language (400 otherwise). - Uncached by design: it carries the generations a write compare-and-sets against. 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 by this route and `POST /translations/{operation}`; a token bound to another project gets 403. Required scope: `translations:read` operationId: listTranslationUnits responses: '200': description: Deterministic, cursor-paged units with summary content: application/json: schema: type: object example: object: list projectId: clz8k2m4n0001qwer7tyu8iop language: id: clz8k2x7y0003lkjh4gfd3sap code: fr-fr name: French data: - id: Y2x6OGszYzlkMDAwN3p4Y3Y4Ym5tMXF3ZQBkYXRhLmhlYWRpbmc format: plain_text source: locale: en-us value: Summer collection generation: sha256:aNCJfb2kY7k558Hq_scUZeouHvrUoY9eaCam_HIB0hk target: locale: fr-fr value: Collection été generation: sha256:zzj5orBWLJCO5eaC_y6jzBO285hKHUQCL5G_-PIhc3A status: current context: pageType: INDEX handle: index section: Heading usages: - / - id: Y2x6OGszZDJlMDAwOHBvaXU3eXRyNmV3cQBkYXRhLmJ1dHRvblRleHQ format: plain_text source: locale: en-us value: Shop now generation: sha256:i5yxt6P8d6YAZqFxmfpJwVd1EG3A-S_s04MP3XTKlHs target: locale: fr-fr value: null generation: null status: missing context: pageType: INDEX handle: index section: Button text usages: - / hasMore: true nextCursor: Y2x6OGszZDJlMDAwOHBvaXU3eXRyNmV3cQBkYXRhLmJ1dHRvblRleHQ summary: current: 18 missing: 5 stale: 2 excluded: 1 '400': description: Unconfigured locale 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: Not found (never discloses other tenants) content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: 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 authentication: a shop API key (WEAVERSE_API_KEY), a scoped API key, a delegated MCP OAuth token, or (translation-unit routes only) a project-bound translation agent token. Scopes: 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/cancel publications, restore versions, publish global sections. content:delete — Delete pages, global sections, languages, static keys, override reverts; required with project:manage for project deletion. project:manage — Create/copy/delete projects, settings, variants, hierarchy, backups, restore-as-new, previews, hostname policy. translations:read — Read translation units only (no general content access). translations:write — Apply translation units only; never mutates page content. A legacy unscoped API key keeps read/write/translation baseline access and every pre-scope endpoint, but never gains publish/delete/project-manage implicitly. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.