Import/Export

Prismic provides utilities for importing and exporting documents to and from your repository.


Prismic's Import/Export tool is handy for many use-cases, such as:

  • migrating content,
  • bulk updates of existing documents,
  • importing translations of documents,
  • importing new documents,
  • and making back-ups.

The Import/Export tool is available starting on the Medium Plan. More about pricing.

Export tool

Prismic's Export tool creates a ZIP file of all published documents in your repository. Here are the steps to perform an export:

  1. In your repository, navigate to Settings > Import/Export > Export your document.
  2. Click on Export your documents. This will create a downloadable snapshot of your documents.
  3. Click the link to download the archive of your documents.
  4. The download is a compressed ZIP file. It contains a folder with JSON files for each of your published documents.

If you need an up-to-date Export after you've performed one, click "Done" and click on "Export your document" again. This will generate a fresh snapshot.

An exported JSON filename looks like this:

Copy
Xr6nORAAAChEyddW$aefa2a44-fa37-46dc-a4fd-7dbdccdd55a2.json

The hash before the $ character is the filename or document ID.

Limitations of Export

  • You can not export releases, drafts, or archived documents.
  • You can not use the Export tool to export Custom Types, Images, or files.
  • We do not recommend this tool to transfer content between the environments or to clone your repository.
  • You can not selectively export documents. All documents are exported.

Import tool

The import tool accepts JSON files compressed in a ZIP archive. (The JSON file structure must be the same as the structure of the file output from an export). You can include up to 200 files in an import job. Imports are rate-limited to 10 operations per hour.

Limitations of the Import tool

Imports must be a ZIP file containing one JSON file for each Document.

  • You can import up to 200 Documents.
  • Import jobs are limited to 10 per hour.
  • The ZIP file size limit is 100MB.
  • The individual JSON file limit is 250000 bytes.
  • For media files, you can only import image types.
  • You cannot add copyright, private notes, image positioning, or crops to Images.
  • When pointing to a media file (media URL or local file path) in your import JSON files, those files will be added to the Media Library of your repository as soon as you launch the Import job. If you delete the Import release after launching the Import job, media files will remain in the Media Library of your repository. Retrying Import jobs several times could lead to duplicates in the Media Library. Find out how to avoid duplicates by referring to the Images section of the Import JSON Reference.
  • The import automatically regenerates thumbnails based on the `origin` data for the main image specified in the Import JSON file. Thus, the image data you provide in Import JSON files for responsive views of a given Image field are ignored in the importing job.
  • Any Content Relationship or Link to another Prismic document will need to be re-added after the import has been done.

Import new documents

Here are the following steps to import one or more new documents to your repository:

  1. Prepare each new document as a JSON file according to your Custom Type for the import, as described in the Import JSON Reference.
  2. Select all the JSON files and compress them directly. Do not compress the folder they are in. Directly select all the files and compress them. Give the compressed file any name.
  3. In your repository, go to Settings > Import/Export > Import your documents.
  4. Click on Choose files and upload the compressed JSON files.
  5. Click Import now. All of your documents will be uploaded and added to a new release. You can give a name to the release, or else it will be auto-named.
  6. Review your new release before publishing. If anything was not imported correctly, you can either edit the documents directly or delete the release and start again.

Be careful when you publish

Once an Import release is published, there is no bulk rollback. Make sure to do the necessary testing before publishing the release.

Update an existing document

Here are the steps to update an existing document:

  1. Export the document.
  2. Make changes in the exported JSON. Do not change your documents' file names.
  3. To re-import documents, select the JSON files and compress them directly. Do not compress the folder they are in. Directly select all the files and compress them.
  4. In your repository, go to Settings > Import/Export > Import your documents.
  5. Click on Choose files and upload JSON files.
  6. Click Import now. All of your documents will be uploaded and added to a new release. You can give a name to the release, or else it will be named automatically.
  7. Review your new release before publishing. If anything was not imported correctly, you can either edit the documents directly or delete the release and start again.

Translate content in bulk

To import translated content for an existing document, you need to import JSON files with a naming convention based on the grouplang ID.

grouplang ID

The grouplang ID is a common identifier for a document and its translations. A document in the master language and all its translations share the same grouplang ID. You can find the grouplang ID at the end of each JSON file when export documents. It looks like this:

Copy
"grouplang": "Xr6nORAAAChEyddY"

Import a new translation for an existing document

To import translated content for an existing document, you need to import files with this naming convention:

Copy
translate_{grouplang}_{lang}

For example: If you want to import an fr-fr translation of an existing en-us document (with the grouplang ID WKq0ph4AACEA4M9B), the JSON file you'll import for the French content needs to be named like this:

Copy
translate_WKq0ph4AACEA4M9B_fr-fr.json

The filename must contain the grouplang ID that you can find in the master language document when exporting it.

Also, make sure you have the right locale code set up in the JSON file itself.

Copy one document to multiple locales at once

You can use the Import and Export feature and some scripting to copy one document to multiple other locales at once. 

  • Publish the original document from the Prismic UI
  • Export your documents using the Export module (you'll get a ZIP archive containing one JSON file for each published document)

Play the following script on the list of documents you want to duplicate to all locales at once:

  • Get the grouplang value from the original document.
  • Generate one JSON file for each language you want to duplicate the document.
  • In each JSON file, replace the lang value with the target locale code (i.e., "lang": "es-es")
  • In each JSON file, insert the grouplang value (the one you grabbed from the original file, i.e.,  "grouplang": "X3dY8hAAACQASEKF")
  • Name each generated files following this convention: translate_{grouplang}_{lang}.json. For example, if you need to generate duplicate JSON files for 3 locales, you’ll end up with these files (assuming the group lang ID of the original is X3dY8hAAACQASEKF):
Copy
translate_X3dY8hAAACQASEKF_fr-fr.json
translate_X3dY8hAAACQASEKF_es-es.json
translate_X3dY8hAAACQASEKF_it-it.json
  • ZIP the generated files
  • Import them using the Import module

Troubleshooting Singletons

You might see an error when trying to import a translation for a document that is of a Singleton type. In that case, switch the type from Singleton to Repeatable. Once you're done with the import, you can change it back to Singleton. 

Import new content in multiple languages

Let's say you have a repository with a Custom Type blog_post that has UID, Title, and Key Text fields.
There are two languages: en-gb and fr-fr where en-gb is the default language.

To import new documents in multiple languages you need to prepare your JSON file in the alternate languages that you'll import.

First, create the files with this naming convention: new_{groupid}_{lang}. Here, groupid is an arbitrary identifier of 16 characters that will be used to match a new document with its translations. Don't use underscore characters in the groupid or else the import will fail.

In our example, filenames should look like:

  • new_abcdefghijklmnop_en-gb.json
  • new_abcdefghijklmnop_fr-fr.json

Then, add the corresponding fields in the Custom Type JSON and lang for each one. Please follow the Import JSON reference guide to prepare the JSON file for the import.

Here is an example of the new_abcdefghijklmnop_en-gb.json file:

Copy
{ 
  "uid": "post",
  "post_title": [
    { "type": "heading1", "content": { "text": "New blog in english", "spans": [] } }
  ],
  "key_text": "This is my Key text in English",
  "type": "blog_post",
  "tags": [],
  "lang": "en-gb"
}

Make sure before importing a set of the localized documents, the corresponding languages/locales are available in your repository. The value of lang in JSON must match the language/locale code in your repository.

Here is an example of the new_myimports_fr-fr.json file:

Copy
{ 
  "uid": "post",
  "post_title": [
    { "type": "heading1", "content": { "text": "New blog in french", "spans": [] } }
  ],
  "key_text": "This is my Key text in french",
  "type": "blog_post",
  "tags": [],
  "lang": "fr-fr"
}

Import a bulk update

  1. Export the content to update
  2. Modify the JSON files. Make the bulk change(s) you need. For example, you could open the files in a code editor such as Visual Studio Code. Most code editors like this will have find-and-replace functionality to make this straightforward. Don't change any of the documents' file names.
  3. Import the updated documents and review the release. Don't forget to re-apply any image cropping or zoom that you had previously as this is lost in the Import and Export process.
  4. If all is well, then you just need to do is publish this release and your new updated content will be live!

Limitations

  • Draft, Archived, and document in Releases aren't included in the process.
  • You will lose Image positioning and zoom of images during this process. You will need to re-apply any image cropping and zoom after running the import. 

Was this article helpful?
Not really
Yes, Thanks

Can't find what you're looking for? Spot an error in the documentation? Get in touch with us on our Community Forum or using the feedback form above.