PHphrase
Uploads

Upload a new file

Upload a new language file. Creates necessary resources in your project.

Note: be aware of upload limits.

post/projects/{project_id}/uploads

Request

Path parameters

project_idstring required

Project ID

Headers

X-PhraseApp-OTPstring

Two-Factor-Authentication token (optional)

Request body multipart/form-data

branchstring

specify the branch to use

filestring binary required

File to be imported

file_formatstring required

File format. Auto-detected when possible and not specified.

locale_idstring required

Locale of the file's content. Can be the name or id of the locale. Preferred is id.

tagsstring

List of tags separated by comma to be associated with the new keys contained in the upload.

update_translationsboolean

Indicates whether existing translations should be updated with the file content.

update_custom_metadataboolean

Determines whether to update custom metadata values when uploading a file. If set to true, existing metadata can be changed or removed. Passing an empty value deletes the corresponding metadata property.

update_translation_keysboolean

Pass false here to prevent new keys from being created and existing keys updated.

update_translations_on_source_matchboolean

Update target translations only if the source translations of the uploaded multilingual file match the stored translations.

source_locale_idstring

Specifies the source locale for multilingual files. Can be the name or id of the locale. Preferred is id.

update_descriptionsboolean

Existing key descriptions will be updated with the file content. Empty descriptions overwrite existing descriptions.

convert_emojiboolean

This option is obsolete. Providing the option will cause a bad request error.

skip_upload_tagsboolean

Indicates whether the upload should not create upload tags.

skip_unverificationboolean

Indicates whether the upload should unverify updated translations.

file_encodingstring

Enforces a specific encoding on the file contents. Valid options are "UTF-8", "UTF-16" and "ISO-8859-1".

locale_mappingobject

Mapping between locale names and translation columns. Required in some formats like CSV or XLSX.

format_optionsobject

Additional options available for specific formats. See our format guide for the complete list.

autotranslateboolean

If set, translations for the uploaded language will be fetched automatically.

verify_mentioned_translationsboolean

Indicates whether all translations mentioned in the upload should be verified.

mark_reviewedboolean

Indicated whether the imported translations should be marked as reviewed. This setting is available if the review workflow is enabled for the project.

tag_only_affected_keysboolean

Indicates whether only keys affected (created or updated) by the upload should be tagged. The default is false

translation_key_prefixstring

This prefix will be added to all uploaded translation key names to prevent collisions. Use a meaningful prefix related to your project or file to keep key names organized.

skip_automated_job_creationboolean

When true, the automation rules for the project will not fire for this upload, so no jobs are created as a side effect of importing this file. Defaults to false.

Example request

{
  "branch": "my-feature-branch",
  "file": "/path/to/my/file.json",
  "file_format": "json",
  "locale_id": "abcd1234cdef1234abcd1234cdef1234",
  "tags": "awesome-feature,needs-proofreading",
  "update_translations": true,
  "update_custom_metadata": true,
  "update_translation_keys": true,
  "update_translations_on_source_match": true,
  "source_locale_id": "abcd1234cdef1234abcd1234cdef1234",
  "update_descriptions": true,
  "convert_emoji": true,
  "skip_upload_tags": true,
  "skip_unverification": true,
  "file_encoding": "UTF-8",
  "autotranslate": true,
  "verify_mentioned_translations": true,
  "mark_reviewed": true,
  "tag_only_affected_keys": true,
  "translation_key_prefix": "prefix_"
}

Response

Created

idstring
filenamestring
formatstring
statestring
tagstring

Unique tag of the upload

tagsstring[]

List of tags that were assigned to the uploaded keys

urlstring

The URL to the upload in Phrase Strings app.

created_atstring date-time
updated_atstring date-time

Example response

{
  "id": "abcd1234cdef1234abcd1234cdef1234",
  "filename": "example.json",
  "format": "json",
  "state": "success",
  "tag": "tag",
  "summary": {
    "locales_created": 2,
    "translation_keys_created": 162,
    "translation_keys_updated": 10,
    "translation_keys_unmentioned": 0,
    "translations_created": 291,
    "translations_updated": 3,
    "tags_created": 2,
    "translation_keys_ignored": 0
  },
  "user": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "username": "johndoe",
    "name": "John Doe",
    "gravatar_uid": "205e460b479e2e5b48aec07710c08d50"
  },
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z"
}

Changes

No recorded changes to this operation across all 1 revision of this API.