> ## Documentation Index > Fetch the complete documentation index at: https://developers.phrase.com/llms.txt > Use this file to discover all available pages before exploring further. # Upload a new file > Upload a new language file. Creates necessary resources in your project. Note: be aware of [upload limits](https://support.phrase.com/hc/en-us/articles/8548271212188-Phrase-Strings-Limits#file-size-upload-limits-0-0). ## OpenAPI ````yaml /openapi/phrase-strings.json post /projects/{project_id}/uploads openapi: 3.0.3 info: title: Phrase Strings API Reference version: 2.0.0 description: >- Phrase Strings is a translation management platform for software projects. You can collaborate on language file translation with your team or order translations through our platform. The API allows you to import locale files, download locale files, tag keys or interact in other ways with the localization data stored in Phrase Strings for your account. contact: name: Phrase Support url: https://developers.phrase.com/api/ email: support@phrase.com x-logo: url: https://developers.phrase.com/images/phrase-logo.svg backgroundColor: '#03eab3' altText: Phrase Strings termsOfService: https://phrase.com/terms/ license: name: MIT url: https://choosealicense.com/licenses/mit/ servers: - url: https://api.phrase.com/v2 description: EU production server - url: https://api.us.app.phrase.com/v2 description: US production server security: - Token: [] - Basic: [] tags: - name: Accounts - name: Authorizations description: > The endpoints provided by the Authorizations API are **only accessible via Basic authentication with email and password**. When creating a new authorization, the new access token for this authorization will be returned in the immediate response but not later, due to security reasons. When accessing authorizations later, you will only see the last eight chars of the token in plain text (`token_last_eight`) and the SHA256 digest of the token for reference (`hashed_token`). For instructions on how authorization in general works, see our [Auth Guide](#overview--authentication). ### Scopes When creating or updating an OAuth authorization, you can define a list of scopes to limit the access that can be performed by that authorization. #### Available Scopes
Scope Description
read Read projects, locales, keys, translations, orders
write Write projects, locales, keys, translations but not orders
orders.create Create and confirm orders
team.manage Manage invitations and members
- name: Blacklisted Keys - name: Branches description: > ### Branch creation Branches will be created asynchronously. State of branch creation is returned as state. #### Available States
State Description
initialized Data received.
processing Branch is currently creating.
success Branch was created successfully
error Branch creation failed.
- name: Comments - name: Comment Reactions - name: Comment Replies - name: Custom Metadata - name: Distributions - name: Documents - name: Figma Attachments - name: Formats - name: Glossaries - name: Glossary Terms - name: Glossary Term Translations - name: ICU - name: Invitations description: > With the invitation endpoint you can [manage and invite users](https://support.phrase.com/hc/en-us/articles/5709742418716) to Phrase Strings via API. A user can have the role Manager, Developer or Translator each with its own access rights. Developers and translators need resources like projects and locales assigned in order to access them. - name: Job Annotations description: > The job annotations endpoints allow you to create, update and delete annotations for jobs and job locales. Annotations are used to add metadata to a job or job locale. - name: Job Comments - name: Job Locales - name: Job Template Locales - name: Job Templates - name: Jobs - name: Keys - name: Linked Keys - name: Locales - name: Locale Downloads - name: Members description: > With the members endpoints you can do basic [team and user management](https://support.phrase.com/hc/en-us/articles/5709742418716) via API. A user can have the role Manager, Developer or Translator each with its own access rights. Developers and translators need resources like projects and locales assigned in order to access them. - name: Notifications - name: Notification Groups - name: Orders description: > ### List of categories [TextMaster] When ordering translations from TextMaster, you need to specify a category ID along with your order. See this list for information on the category ID and their equivalent description.
Category ID Description
C001Agriculture
C002Aerospace
C003Animals/Pets/Plants
C004Arts/Culture/Literature
C005Automotive/Transportation
C006Computers/Technology/Software
C007Telecom
C008Real Estate/Construction/Building
C009Consumer Goods
C010Education
C011Entertainment
C012Ecology/Environment
C013Health/Biotechnology/Pharma
C014Internet
C015Policy/Government/Public
C016Publishing/Media/Communication
C017Religion
C018Food/Beverages
C019Retail
C020Fashion/Luxury/Textiles
C021Travel/Tourism
C022Natural Resources/Energy
C023Banking/Financial Services/Insurance
C024Legal Affairs/Tax/Law
C025Raw Materials/Industrial Goods
C026Lifestyle/Leisure/Hobbies
C027Sports
C028Home/Family/Friends/Children
C029Economy/Financial Markets
C030Science
C031Human Resources/Employment
C032Adult (Pornography, Violence, etc.)
- name: Organization Job Template Locales - name: Organization Job Templates - name: Projects - name: Quality - name: Releases - name: Release Triggers - name: Repo Syncs description: > The Repo Syncs API allows you to synchronize your Phrase projects with your code repositories. You can import translations from your repository to Phrase and export translations from Phrase to your repository. - name: Repo Sync Events - name: Reports - name: Search - name: Screenshot Markers - name: Screenshots - name: Spaces - name: Style guides - name: Tags - name: Teams - name: Translations - name: Uploads description: > ### Formats We support all common localization file formats. For a detailed overview, see our [Format Guide](https://support.phrase.com/hc/en-us/sections/6111343326364). ### Processing Uploads will be processed asynchronously and thus the data might not be imported yet although the upload is completed. Therefore we recommend to evaluate the returned state field for information on the import progress. #### Available States
State Description
initialized Data received.
waiting_for_preview Upload is waiting for preview to be finished.
waiting Upload is waiting for processing.
processing Upload is being processed, data is currently imported.
success Upload is complete and all data is imported.
error Upload or import process failed.
- name: Users - name: Variables - name: Versions / History - name: Webhooks - name: Webhook Deliveries paths: /projects/{project_id}/uploads: post: tags: - Uploads summary: Upload a new file description: > Upload a new language file. Creates necessary resources in your project. Note: be aware of [upload limits](https://support.phrase.com/hc/en-us/articles/8548271212188-Phrase-Strings-Limits#file-size-upload-limits-0-0). operationId: upload/create parameters: - $ref: '#/components/parameters/X-PhraseApp-OTP' - $ref: '#/components/parameters/project_id' requestBody: required: true content: multipart/form-data: schema: type: object title: upload/create/parameters required: - file - file_format - locale_id properties: branch: description: specify the branch to use type: string example: my-feature-branch file: description: File to be imported type: string format: binary example: /path/to/my/file.json file_format: description: File format. Auto-detected when possible and not specified. type: string example: json locale_id: description: >- Locale of the file's content. Can be the name or id of the locale. Preferred is id. type: string example: abcd1234cdef1234abcd1234cdef1234 tags: description: >- List of tags separated by comma to be associated with the new keys contained in the upload. type: string example: awesome-feature,needs-proofreading update_translations: description: >- Indicates whether existing translations should be updated with the file content. type: boolean example: true update_custom_metadata: description: >- 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. type: boolean default: true example: true update_translation_keys: description: >- Pass `false` here to prevent new keys from being created and existing keys updated. type: boolean default: true example: true update_translations_on_source_match: description: >- Update target translations only if the source translations of the uploaded multilingual file match the stored translations. type: boolean default: false example: true source_locale_id: description: >- Specifies the source locale for multilingual files. Can be the name or id of the locale. Preferred is id. type: string example: abcd1234cdef1234abcd1234cdef1234 update_descriptions: description: >- Existing key descriptions will be updated with the file content. Empty descriptions overwrite existing descriptions. type: boolean example: true convert_emoji: description: >- This option is obsolete. Providing the option will cause a bad request error. type: boolean example: true deprecated: true skip_upload_tags: description: Indicates whether the upload should not create upload tags. type: boolean example: true skip_unverification: description: >- Indicates whether the upload should unverify updated translations. type: boolean example: true file_encoding: description: >- Enforces a specific encoding on the file contents. Valid options are "UTF-8", "UTF-16" and "ISO-8859-1". example: UTF-8 type: string locale_mapping: description: >- Mapping between locale names and translation columns. Required in some formats like CSV or XLSX. type: object properties: {} example: '{"en": "2"}' format_options: description: >- Additional options available for specific formats. See our format guide for the [complete list](https://support.phrase.com/hc/en-us/articles/9652464547740-List-of-Supported-File-Types-Strings). type: object properties: {} example: '{"foo": "bar"}' autotranslate: description: >- If set, translations for the uploaded language will be fetched automatically. type: boolean example: true verify_mentioned_translations: description: >- Indicates whether all translations mentioned in the upload should be verified. type: boolean default: false example: true mark_reviewed: description: >- Indicated whether the imported translations should be marked as reviewed. This setting is available if the review workflow is enabled for the project. type: boolean example: true tag_only_affected_keys: description: >- Indicates whether only keys affected (created or updated) by the upload should be tagged. The default is `false` type: boolean default: false example: true translation_key_prefix: description: >- 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. type: string example: prefix_ responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/upload' headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' '400': $ref: '#/components/responses/400' '404': $ref: '#/components/responses/404' '429': $ref: '#/components/responses/429' x-code-samples: - lang: Curl source: |- curl "https://api.phrase.com/v2/projects/:project_id/uploads" \ -u USERNAME_OR_ACCESS_TOKEN \ -X POST \ -F branch=my-feature-branch \ -F file=@/path/to/my/file.json \ -F file_format=json \ -F locale_id=abcd1234cdef1234abcd1234cdef1234 \ -F tags=awesome-feature,needs-proofreading \ -F locale_mapping[en]=2 \ -F format_options[foo]=bar - lang: CLI v2 source: |- phrase uploads create \ --project_id \ --branch my-feature-branch \ --file /path/to/my/file.json \ --file_format json \ --locale_id abcd1234cdef1234abcd1234cdef1234 \ --tags awesome-feature,needs-proofreading \ --locale_mapping '{"en": "2"}' \ --format_options '{"foo": "bar"}' \ --access_token components: parameters: X-PhraseApp-OTP: in: header name: X-PhraseApp-OTP description: Two-Factor-Authentication token (optional) required: false allowEmptyValue: false schema: type: string project_id: in: path name: project_id description: Project ID required: true schema: type: string schemas: upload: type: object title: upload properties: id: type: string filename: type: string format: type: string state: type: string tag: type: string description: | Unique tag of the upload tags: type: array items: type: string description: | List of tags that were assigned to the uploaded keys url: type: string description: | The URL to the upload in Phrase Strings app. user: $ref: '#/components/schemas/user_preview' type: object summary: type: object properties: locales_created: type: integer translation_keys_created: type: integer translation_keys_updated: type: integer translation_keys_unmentioned: description: > The number of translation keys in the project that were not mentioned in the upload. Note: this field is not calculated (and shows 0) if the upload contains more than 10,000 keys. type: integer translations_created: type: integer translations_updated: type: integer tags_created: type: integer translation_keys_ignored: type: integer processed_translations: type: integer upload_total_translations: type: integer created_at: type: string format: date-time updated_at: type: string format: date-time example: 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' user_preview: type: object title: user_preview properties: id: type: string username: type: string name: type: string gravatar_uid: type: string example: id: abcd1234cdef1234abcd1234cdef1234 username: johndoe name: John Doe gravatar_uid: 205e460b479e2e5b48aec07710c08d50 headers: X-Rate-Limit-Limit: description: The number of allowed requests in the current period schema: type: integer X-Rate-Limit-Remaining: description: The number of remaining requests in the current period schema: type: integer X-Rate-Limit-Reset: description: >- Timestamp of end of current time period as UNIX timestamp, see [Rate Limiting](/en/api/strings/pagination#rate-limiting) schema: type: integer responses: '400': description: Bad request headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' '404': description: Not Found headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' '429': description: Rate Limiting headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' securitySchemes: Token: type: apiKey in: header name: Authorization description: Enter your token in the format `token TOKEN` Basic: type: http scheme: basic ````