Uploading localization files

This guide describes the easiest way to import your existing localization files into your localization project in Phrase.

Uploading localization files

Phrase is built to help you effortlessly manage your translation process online. Therefore, you need to feed it with the content you wish to eventually retrieve in multiple languages. During an upload, Phrase will process your file in the background and extract the translation data into your project for you to start working on the actual translation right away.

Uploading localization files from your application to Phrase is the easiest way to import your existing translation resources into your Phrase localization project. We support a huge variety of ways to import your translations including all common localization file formats.

You can upload files in the Translation Center, via the API or via our command-line client.

Uploading translation files via Translation Center

File & Settings 

Uploading files within the Translation Center is easy. You only need to follow these simple steps to ensure your translations properly arrive in Phrase.

  1. Make sure your translation file is formatted correctly. You can have a look at example files in our format guide.
  2. Select your file in the file browser or drag and drop it from your computer.
  3. Select the file format of your upload file in the dropdown menu. We narrowed down suggestions based on your file and listed them first.
  4. Select the language of the file content. If this information is not already provided in your file, choose to create a new language or upload the content to an existing language.

Update translations

By default Phrase will only extract new content and thus not delete or update any existing keys in your localization project. Phrase will scan your file and only import new keys or translations that are not already stored inside Phrase. No data will be lost by uploading files. However, if you want to overwrite existing data, respectively replace your Phrase project resources with the content from your localization file, we do offer the Update translations option. This option is available within the Translation Center upload interface and via the API. Your existing translations will be overwritten with the content of the uploaded localization file.

To prevent data loss, make sure that you download the latest changes to your localization file from Phrase before changing it and uploading it again with the Update translations option.

Update descriptions

Select this option if you want to update all descriptions of the keys from the uploaded file. Empty descriptions overwrite existing ones. Descriptions can contain any additional information for your translators. This might come in handy when going through individual keys in the Translation Editor.

Skip upload tags

In order to keep your translations well organized you can add multiple tags to your keys with meaningful labels. Select this option to prevents new keys being tagged with an upload-tag automatically. Learn more about working more efficiently with Tags here.


You can specify the encoding (e.g. UTF-8) of your file or let us guess it for you.


Skip unverification prevents the need to verify non-main language translations again when updating translations.

Marking translations as reviewed treats all uploaded translations as reviewed. This option is available when having activated the Advanced Review Workflow. It allows you to mark keys as ready for being pushed to production.

Upload summary

Failed upload

If your file could not be processed properly you’ll be provided with error details that let you analyze what went wrong. In this example, we show you which line contains content that is not properly formatted for the selected file format.

Successful upload

After the successful processing of your translation file, you’re being redirected to a summary page, that gives you an overview of your upload. Besides importing another file, you can jump right into the Translation Editor to start working on your uploaded keys, create a Job for them or order professional translations via our partners.

Removing keys

To prevent accidental deletion of keys when you remove keys from your localization file and upload it again, we do not automatically delete those keys on Phrase. However, we do offer an easy way to remove those keys, too:

  1. Upload your file through the Translation Center
  2. Click “Delete” and choose “Delete unmentioned keys”
  3. Confirm your selection

All keys and associated translations that were not included in the file you uploaded will be removed from your Phrase project.

Undo an upload

Every upload triggers multiple actions and can modify a lot of data in your projects. Thus we do not offer a simple undo. However, Phrase allows you to easily remove keys that were (wrongly) introduced by a file you uploaded:

  1. Go to the upload summary of the affected upload
  2. Click “Delete” and choose “Delete created keys”
  3. Confirm your selection

All keys and associated translations created by that upload will be removed. Please note that translations for keys that existed prior to the upload will not be removed. To remove individual translations, you can use the version history for each translation.

Upload archive

Select the project and go to Uploads to access the upload archive. The upload archive lists all uploads you have made in the past. Beyond the processing status, you can access the detailed upload summary of affected resources by clicking on a listed upload. Additionally, you can find all successful uploads in your project’s activity stream.


I receive an error message when uploading a file, what do I do?

Please make sure that the file you’re uploading is included in the formats we support. Make sure your file does not contain any syntax errors or invalid characters. Please also verify that you selected the correct character encoding. If you still experience issues, please contact our support team for assistance.

What are upload tags and how can I disable them?

All keys created through an upload are automatically tagged with an upload tag. This new tag can be used to filter search results or API responses. Every upload tag includes a timestamp that indicates the upload date.

The number of upload tags can grow quickly, if you upload a lot of files or if you choose the Update translations option. You can skip the automatic generation of upload tags by selecting the Skip upload tags option to avoid this.

I have a lot of duplicate keys after uploading a file - what happened?

When you upload a file and don’t specify a character encoding explicitly, Phrase tries to guess the encoding. This can in rare cases lead to an incorrect encoding which results in duplicate keys being added to your project. If this happened to you, remove the duplicate keys (see “Undo an upload”) and upload the file again with a correctly specified character encoding.