---
title: "List Translations"
method: GET
path: "/v1/projects/{project_id}/translations"
tags: ["translations"]
---

# List Translations

`GET /v1/projects/{project_id}/translations`

## Request

- Base URL: `https://api.sonenta.dev`
- URL: `https://api.sonenta.dev/v1/projects/{project_id}/translations`
- Auth: none declared

## Path parameters

- `project_id` string, required

## Query parameters

- `language_id` string, required: language uuid (required)
- `namespace_id` string, nullable
- `version_id` string, nullable: Filter by version uuid. Omitted = production version.
- `status` 'missing' | 'draft' | 'translated' | 'reviewed' | 'approved' | 'rejected', nullable
- `author` 'ai' | 'human', nullable: Filter by last-writer kind. Orthogonal to `status`; only matches rows that have a translation.
- `pending_review` boolean: Shortcut for status=translated AND author=ai (AI translations awaiting human review).
- `confidence` string, nullable: Filter by the AGENT's stated confidence on the value (high|medium|low). Only matches rows carrying one (agent-proposed, not yet human-edited).
- `task` string, nullable: Restrict to the exact keys a task points at (its `payload.key_uuids`), addressed by the task's uuid or #number. Scopes the editor to that task's work.
- `q` string, nullable: substring match on key name
- `type` string[], nullable: filter by key type(s) (repeatable)
- `surface` string: Which overlay to list (task 1482). 'base' (default) = the normal translation value (unchanged behaviour). An a11y surface (aria_label|alt_text|screen_reader|plain_language) lists that surface's VALUE per target language for keys where the surface is type-relevant AND a source value exists; status=missing => target untranslated, otherwise the override status. a11y MODERATION stays in the a11y review queue.
- `overrides_only` boolean: Overlay locales only: keep only keys whose OWN value differs from the resolved parent (parity with coverage override_count). Ignored for base languages (no fallback).
- `include_source` boolean: Attach `source_value` (the source-language value, joined by key_uuid) to each item — aligned to the filtered set in one call.
- `has_source` boolean, nullable: Filter by SOURCE-language value presence (orthogonal to `status`, which is the TARGET status). has_source=false keeps only source-missing keys (empty/absent source value); true keeps only keys with a present source. Applied server-side so `total` + cursor stay correct across pages.
- `orphan` boolean, nullable: Code-occurrences ORPHAN filter. true = ONLY orphan keys (the scan FOUND them and they then DISAPPEARED from the code — a `gone` occurrence and NO present one), false = only non-orphans, absent = all. A key never seen by a scan (manual add) is NOT an orphan. Server-side (injected into the key query) so `total` + cursor stay correct. Meaningful only when the response's `measured` is true (else nothing is an orphan).
- `include_ratings` boolean: Attach the end-user 5-star aggregate (avg_rating + rating_count) per key+language. Requires the feedback module to be active (else 403).
- `min_avg_stars` number, nullable: Keep only items whose avg_rating >= this (implies include_ratings).
- `max_avg_stars` number, nullable: Keep only items whose avg_rating <= this (implies include_ratings).
- `include_deleted` boolean: Include keys in the recycle bin (soft-deleted, task 781). Default FALSE excludes trashed keys — aligned with GET /keys + coverage, so the editor never lists a trashed key (which would 404 on /variants). The founder override-matrix 404 bug (client-admin propose).
- `include_overlays` boolean: Attach `overlays` (device surfaces + a11y treatments present) per key, joined by key_uuid in ONE aggregation (no per-key N+1). Lets the 2-line row render overlay icons without calling /variants + /a11y-signals per key. Scope via `overlays_scope`.
- `overlays_scope` 'all' | 'language': Scope of `overlays` presence (only when include_overlays). 'all' (default, founder/master UX) = the key carries the overlay in ANY language; 'language' = only overlays in the requested `language_id`. Both are one indexed aggregation.
- `cursor` string, nullable
- `limit` integer

## Response `200`

Successful Response

- TranslationPage
  - `items` TranslationListItem[], required
    - `key` KeyEmbed, required
      - `uuid` string, required
      - `name` string, required
      - `namespace_uuid` string, required
      - `description` string, nullable
      - `context` string, nullable
      - `plurals` boolean
      - `max_length` integer, nullable
      - `type` string
    - `translation` TranslationCore, required
      - `uuid` string, required
      - `key_uuid` string, required
      - `language_uuid` string, required
      - `value` string, required
      - `status` 'missing' | 'draft' | 'translated' | 'reviewed' | 'approved' | 'rejected', required
      - `version` integer, required
      - `updated_by_uuid` string, nullable, required
      - `updated_by_is_bot` boolean
      - `updated_by_name` string, nullable
      - `proposal_origin` string, nullable
      - `agent_confidence` string, nullable
      - `review_comment` string, nullable
      - `plural_forms` object, nullable
      - `glossary_violations` AppServicesGlossaryMatchGlossaryViolation[], nullable
        - `rule_type` 'translation' | 'do_not_translate' | 'forbidden', required
        - `term` string, required
        - `matched_text` string, nullable
        - `message` string, required
      - `surface` string
      - `created_at` string, date-time, required
      - `updated_at` string, date-time, required
    - `source_value` string, nullable
    - `source_plural_forms` object, nullable
    - `avg_rating` number, nullable
    - `rating_count` integer
    - `overlays` OverlayPresence
      - `surfaces` string[]
      - `a11y` string[]
      - `has_regional_variants` boolean
    - `referenced` boolean, nullable
    - `orphan` boolean, nullable
  - `cursor_next` string, nullable, required
  - `total` integer, required
  - `measured` boolean

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/sonenta/apis/sonenta-api.md) · [All operations](https://skmtc.dev/sonenta/apis/sonenta-api/llms.txt) · [OpenAPI document](https://skmtc.dev/sonenta/apis/sonenta-api/revisions/f853ea49fb05?raw)