The Gatsby Localization App Starter is a Gatsby.js boilerplate for building multilingual websites with content managed in Cosmic JS, a headless CMS.
What is the Gatsby Localization App Starter?
This starter is a pre-configured Gatsby project that pairs the Gatsby static site generator with Cosmic JS's localization features. It takes a Cosmic JS Bucket containing blog-posts and pages object types as input and outputs a static site with a locale selector for switching between translated versions. Built by Cosmic JS, the starter runs on Node.js and uses gatsby-source-cosmicjs to pull content into GraphQL during the build.
Key Features
- Cosmic JS source plugin — Uses
gatsby-source-cosmicjswith configurable bucketSlug, objectTypes (blog-posts, pages), and an optional read key for private buckets. - Localization-ready components — Includes a LocaleSelector atom, a withLocale higher-order component in modules, and HTMLContentArea for rendering localized rich text.
- Modular architecture — Source is organized into atoms (HeaderNav, PostTile), molecules (Header, Footer, PostList), layouts (Blog, Default), and modules (BlogPost, SitePage, SitePostListing) for reuse.
- Styling with Emotion — Ships with
gatsby-plugin-emotionfor CSS-in-JS styling, and a GlobalStyles component inside the layouts/common folder. - SEO via React Helmet — Includes
gatsby-plugin-react-helmetand a Head component for managing meta tags and document head. - Two-file configuration —
gatsby-config.jstargets your Cosmic JS bucket;config.jsholds front-end settings. - Demo and source install options — Install instantly from the Cosmic JS App Section or clone the GitHub source, run
npm install, and start on localhost:8000. - Blog and page templates — Provides a home page, a site page module, and a blog post listing with PostTile components, ready for content from Cosmic JS.
Who should use this starter?
- Gatsby developers — Skim the project structure and config to learn how Cosmic JS content is queried and rendered with locale support.
- Teams adopting Cosmic JS — Use this as a base for any multilingual marketing site or blog where editors manage translations in the Cosmic JS dashboard.
- Agencies prototyping i18n — Stand up a localized Gatsby demo in minutes by installing from the Cosmic JS App Section.
What can you do with it?
- Launch a multilingual blog — Add blog posts to a Cosmic JS Bucket with locale variants; the starter renders a post listing and individual blog post pages with a locale selector.
- Build a localized company site — Use the pages object type and SitePage module to serve translated versions of landing or about pages.
- Experiment with Gatsby i18n — Modify the LocaleSelector and withLocale logic to see how locales are passed through GraphQL queries and components.
How does the installation work?
Two paths exist: install from the Cosmic JS App Section using their web UI, which walks you through account creation and bucket setup, or clone the GitHub repository and run npm install. After either path, edit gatsby-config.js to set your bucketSlug and, if required, an apiAccess read key, then confirm your bucket contains blog-posts and pages object types. Start development with npm start or npm run develop, and the site runs by default at localhost:8000.
Frequently asked questions
What is the default port for the development server?
The starter runs on port 8000 on localhost by default. The console output of the npm start or npm run develop command will tell you if the port has been overridden.
Which Cosmic JS object types are required?
The repository expects your bucket to have blog-posts and pages object types. Without these, the gatsby-source-cosmicjs plugin will not have the correct Gatsby GraphQL queries and the demo will not run.
Do I need an API read key?
Only if your Cosmic JS Bucket is configured to require one. In gatsby-config.js, you can leave the read key blank for public buckets, but a private bucket needs a valid key for Gatsby to fetch content.
How do I configure which bucket the site reads from?
Set the bucketSlug in the gatsby-source-cosmicjs options inside gatsby-config.js to match your own Cosmic JS Bucket slug. That plugin config is the single source of truth for content sourcing.
Can I install this starter without touching code?
Yes. The Cosmic JS App Section offers an install flow that creates a clone of the starter application from the web UI, prompting you through account and bucket creation.
