ℹ️ Based on our Getting Started tutorial in its completed state.
This website supports localization in two flavours:
- Field-level localization is supported by both Contentful and Stackbit. It is only used here for the "Header Text" field in the Site Configuration content object.
- Document-level localization is not directly supported by Contentful. However, by configuring Stackbit appropriately, the visual editor provides a native-like localization experience at the content object-level for all localized models. See Stackbit config file.
Locale-aware routing in the website is implemented via Next.js i18n. Note that for the default locale (en-US in this site) no locale prefix is added to pathnames. See Next.js config file.
Notes:
- When switching between locales, the client-side code is navigating to the same route but with the selected locale. If there's no such page, a 404 page is shown (defining a different behavior is up to you).
- The code implements bi-directional syncing between the locale switcher in the Stackbit visual editor (which controls which pages & fields you can see & edit) and the custom locale switcher rendered in the header of all site pages. This is fully optional, but makes for a more streamlined experience for editors working on multiple locales.
There are two ways to start using this project: importing it via the UI, or developing locally.
To create a cloud-based Stackbit project based on this repository, click here.
You will need to connect your Contentful account (create a free account if needed), and a new Contentful space with sample content will be created for you.
A new GitHub repository with this codebase will be created for you. You can transfer ownership of the duplicated repository to you through the Project Settings.
Lastly, a live production build of the website on Netlify is automatically provisioned.
Before you begin, please make sure you have the following:
- Contentful account
- Node v14 or later
Clone this repository, then run npm install in its root directory.
After signing into Contentful, create a new space.
If you don't already have a management token (or personal access token), generate one. To do so, go into your new empty space, then:
- Click Settings
- Choose API Keys
- Select the Content management tokens tab
- Click the button to generate a new token
From the same place you generated the management token, you can now generate API access keys.
- Select the content delivery / preview tokens tab
- Choose Add API key
In your project, duplicate .env.example to .env.
Fill in the values in the file based on the keys you've created.
Note: the Contentful space ID can be viewed and copied via Settings->General Settings in Contentful.
Import the provided content models & content into Contentful by running the import.js script:
node ./contentful/import.js
If the import fails to run, make sure that you've run npm install and that all keys in your .env file are set correctly.
Run the Next.js development server:
npm run dev
Visit localhost:3000 and you should see the example content you imported into your new Contentful space.
Keep the Next.js development server running, and open a new command-line window in the same directory.
Install Stackbit's CLI tools (once):
npm i -g @stackbit/cli@latest
Run the CLI:
stackbit dev
Click the displayed link to localhost:8090/_stackbit and the visual editor will open.
To deploy a cloud-based Stackbit project connected to your repository:
- Push your code to a GitHub repository (preferably, push only the contents of this directory as a new repository).
- Open the import page and choose Use my repository.
If you get stuck along the way, drop into our Discord server and send a message in the #documentation or #help channels.