---
title: "Overwrite translations"
method: POST
path: "/v2/projects/{projectId}/files/translations/overwrite"
tags: ["Files"]
---

# Overwrite translations

`POST /v2/projects/{projectId}/files/translations/overwrite`

## Request

- Base URL: `https://api.gtx.dev`
- URL: `https://api.gtx.dev/v2/projects/{projectId}/files/translations/overwrite`
- Auth: HTTP bearer

Replace 1–100 existing translations with full translated file content. Requires `project:files:write`.

## Path parameters

- `projectId` string, required

## Headers

- `gt-api-version` '2025-01-01.v0' | '2025-11-03.v1' | '2026-02-18.v1' | '2026-03-06.v1' | '2026-10-08.v1', required

## Request body

- object
  - `diffs` object[], required: 1–100 translations; each branch, file, version and locale may appear once.
    - `locale` string, required
    - `diff` string, required
    - `branchId` string
    - `versionId` string, required
    - `fileId` string, required
    - `localContent` string, required: The full translated file content.

## Response `200`

Overwrite result for each translation, in request order, even when every translation fails; a translation fails when its source file or translation does not exist, the content does not apply to its format, or the save fails. Retrying with the same content is safe.

- object
  - `summary` BatchWriteSummary, required: Number of `results` in total and by `status`.
    - `total` integer, required
    - `succeeded` integer, required
    - `failed` integer, required
  - `results` object[], required: One result per translation, in request order.
    - `branchId` string, required
    - `fileId` string, required
    - `versionId` string, required
    - `locale` string, required
    - `status` 'succeeded' | 'failed', required
    - `error` string: Why the item failed.
    - `code` 'invalid_request' | 'unauthenticated' | 'payment_required' | 'permission_denied' | 'not_found' | 'conflict' | 'route_retired' | 'payload_too_large' | 'unsupported_media_type' | 'locked' | 'not_ready' | 'rate_limited' | 'internal_error' | 'upstream_error' | 'unavailable' | 'already_exists' | 'api_key_invalid' | 'api_version_too_old' | 'api_version_unsupported' | 'branch_not_found' | 'cdn_not_enabled' | 'content_empty' | 'credits_insufficient' | 'cursor_invalid' | 'default_branch_conflict' | 'drive_access_insufficient' | 'drive_account_not_connected' | 'file_too_large' | 'google_account_not_linked' | 'integration_managed_file' | 'integration_not_connected' | 'invalid_content_encoding' | 'ip_not_allowed' | 'layout_not_supported' | 'locale_not_allowed' | 'org_integration_required' | 'permission_missing' | 'permission_not_grantable' | 'plan_feature_unavailable' | 'project_limit_reached' | 'response_too_large' | 'source_file_not_found' | 'spend_limit_reached' | 'sync_required' | 'target_inaccessible' | 'target_locales_missing' | 'translation_not_ready' | 'unsupported_content_encoding' | 'upload_incomplete' | 'usage_limit_reached': Machine-readable cause of the failure. Present when `error` is.

## Other responses

- `400`: The request is malformed or failed validation.
- `401`: Authentication is missing or invalid.
- `403`: The caller is authenticated but not allowed to perform this operation or access the requested resource.
- `413`: The request, or the data it would return, exceeds a size or item limit.
- `415`: The request body's Content-Type is missing or not supported, or its Content-Encoding is not supported. Send the body as application/json, uncompressed or gzip-encoded.
- `429`: Too many requests. The rate limit was exceeded.
- `500`: An unexpected server error occurred.

## Changes

- **2026-11-06** `39f0059275f1`: 18 warning
  - added the new `invalid_content_encoding` enum value to the `allOf[#/components/schemas/ErrorResponse]/code` response property for the response status `400`
  - added the new `invalid_content_encoding` enum value to the `allOf[#/components/schemas/ErrorResponse]/code` response property for the response status `401`
  - added the new `invalid_content_encoding` enum value to the `allOf[#/components/schemas/ErrorResponse]/code` response property for the response status `403`
  - added the new `invalid_content_encoding` enum value to the `allOf[#/components/schemas/ErrorResponse]/code` response property for the response status `413`
  - …14 more
- **2026-11-05** `d8e2891005f3`: 8 warning
  - added the new `integration_managed_file` enum value to the `allOf[#/components/schemas/ErrorResponse]/code` response property for the response status `400`
  - added the new `integration_managed_file` enum value to the `allOf[#/components/schemas/ErrorResponse]/code` response property for the response status `401`
  - added the new `integration_managed_file` enum value to the `allOf[#/components/schemas/ErrorResponse]/code` response property for the response status `403`
  - added the new `integration_managed_file` enum value to the `allOf[#/components/schemas/ErrorResponse]/code` response property for the response status `413`
  - …4 more
- …earlier changes not shown

[Operation history](https://skmtc.dev/generaltranslation/apis/general-translation-api/changes/v2/projects/:projectId/files/translations/overwrite/post.md)

---

[API](https://skmtc.dev/generaltranslation/apis/general-translation-api.md) - [All operations](https://skmtc.dev/generaltranslation/apis/general-translation-api/llms.txt) - [OpenAPI document](https://skmtc.dev/generaltranslation/apis/general-translation-api/revisions/1ebafb7f823e?raw)
