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

# Upload translations

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

## Request

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

Upload translations of 1–100 existing source files. 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
  - `data` object[], required: 1–100 source files with their translations; each file and locale may appear once.
    - `source` union, required
      - object
        - `fileName` string, required
        - `fileFormat` 'GTJSON' | 'JSON' | 'YAML' | 'MD' | 'MDX' | 'TS' | 'JS' | 'HTML' | 'TXT' | 'PO' | 'POT' | 'TWILIO_CONTENT_JSON' | 'LOTTIE' | 'SVG' | 'XCSTRINGS' | 'DOT_STRINGS' | 'DOT_STRINGSDICT' | 'ANDROID_STRINGS' | 'SRT' | 'RESX' | 'PNG' | 'JPEG' | 'MP4', required
        - `dataFormat` 'JSX' | 'ICU' | 'I18NEXT' | 'STRING'
        - `locale` string, required
        - `fileId` string
        - `versionId` string
        - `branchId` string
        - `checkedOutBranchId` string
        - `incomingBranchId` string
        - `content` string, required: Base64-encoded file content.
      - object
        - `fileName` string, required
        - `fileFormat` 'GTJSON' | 'JSON' | 'YAML' | 'MD' | 'MDX' | 'TS' | 'JS' | 'HTML' | 'TXT' | 'PO' | 'POT' | 'TWILIO_CONTENT_JSON' | 'LOTTIE' | 'SVG' | 'XCSTRINGS' | 'DOT_STRINGS' | 'DOT_STRINGSDICT' | 'ANDROID_STRINGS' | 'SRT' | 'RESX' | 'PNG' | 'JPEG' | 'MP4', required
        - `dataFormat` 'JSX' | 'ICU' | 'I18NEXT' | 'STRING'
        - `locale` string, required
        - `fileId` string
        - `versionId` string
        - `branchId` string
        - `checkedOutBranchId` string
        - `incomingBranchId` string
        - `upload` object, required: A file already PUT to the URL from Create file uploads, in place of `content`; required for files over 4MB.
          - `sha256` string, required: SHA-256 of the file's bytes, as 64 lowercase hex characters.
    - `translations` union[], required
      - union
        - object
          - `fileName` string, required
          - `fileFormat` 'GTJSON' | 'JSON' | 'YAML' | 'MD' | 'MDX' | 'TS' | 'JS' | 'HTML' | 'TXT' | 'PO' | 'POT' | 'TWILIO_CONTENT_JSON' | 'LOTTIE' | 'SVG' | 'XCSTRINGS' | 'DOT_STRINGS' | 'DOT_STRINGSDICT' | 'ANDROID_STRINGS' | 'SRT' | 'RESX' | 'PNG' | 'JPEG' | 'MP4', required: The translation's format, saved as sent: the source's format or a supported conversion from it (POT to PO).
          - `dataFormat` 'JSX' | 'ICU' | 'I18NEXT' | 'STRING'
          - `locale` string, required
          - `content` string, required: Base64-encoded translation content.
        - object
          - `fileName` string, required
          - `fileFormat` 'GTJSON' | 'JSON' | 'YAML' | 'MD' | 'MDX' | 'TS' | 'JS' | 'HTML' | 'TXT' | 'PO' | 'POT' | 'TWILIO_CONTENT_JSON' | 'LOTTIE' | 'SVG' | 'XCSTRINGS' | 'DOT_STRINGS' | 'DOT_STRINGSDICT' | 'ANDROID_STRINGS' | 'SRT' | 'RESX' | 'PNG' | 'JPEG' | 'MP4', required: The translation's format, saved as sent: the source's format or a supported conversion from it (POT to PO).
          - `dataFormat` 'JSX' | 'ICU' | 'I18NEXT' | 'STRING'
          - `locale` string, required
          - `upload` object, required: A file already PUT to the URL from Create file uploads, in place of `content`; required for files over 4MB.
            - `sha256` string, required: SHA-256 of the file's bytes, as 64 lowercase hex characters.

## Response `200`

Upload result for each translation, in request order, even when every translation fails to save: a failed translation has `status: "failed"` and an `error` while the others are saved. Retrying with the same content is safe; translations that were already saved are saved again, which can repeat completed webhooks and revisions.

- 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 uploaded translation, in request order.
    - `branchId` string, required
    - `fileId` string, required
    - `versionId` string, required
    - `fileName` string, required
    - `fileFormat` 'GTJSON' | 'JSON' | 'YAML' | 'MD' | 'MDX' | 'TS' | 'JS' | 'HTML' | 'TXT' | 'PO' | 'POT' | 'TWILIO_CONTENT_JSON' | 'LOTTIE' | 'SVG' | 'XCSTRINGS' | 'DOT_STRINGS' | 'DOT_STRINGSDICT' | 'ANDROID_STRINGS' | 'SRT' | 'RESX' | 'PNG' | 'JPEG' | 'MP4', required
    - `dataFormat` 'JSX' | 'ICU' | 'I18NEXT' | 'STRING' | 'MESSAGE_TREE'
    - `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, including a translation whose content is not valid base64 or does not parse in its format. Nothing is saved, and the error names each such translation by its index, fileName and locale.
- `401`: Authentication is missing or invalid.
- `403`: The caller is authenticated but not allowed to perform this operation or access the requested resource.
- `404`: A source file does not exist. Nothing is saved.
- `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, or translations were saved but the source files' locale list could not be updated; the error then lists saved and failed files.
- `503`: The server is too busy to process the uploaded files. Retry later.

## Changes

- **2026-11-14** `1ebafb7f823e`: 1 warning
  - added the new `MESSAGE_TREE` enum value to the `results/items/dataFormat` response property for the response status `200`
- **2026-11-07** `3526a10f9f7a`: 1 warning
  - removed the request property `data/items/source/allOf[subschema #1]/formatMetadata`
- **2026-11-06** `39f0059275f1`: 22 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 `404`
  - …18 more
- …earlier changes not shown

[Operation history](https://skmtc.dev/generaltranslation/apis/general-translation-api/changes/v2/projects/:projectId/files/translations/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)
