Localize your content

This quick start guide will cover the bare minumum you need to get up and running. For more detailed information, check out the Localization documentation

Configure your locales

Project-level locale configuration lives in the /src/config-locales.js file. Assuming you have not overridden this file via a custom corgi template, your project's default locale will be "en", with two other default locales of "fr" and "es". Edit this data per your project's needs, ensuring that the strings entered correspond with what you want your URLs to look like. For more information, check out the locale config documentation

Add locale-specific content

This is just a quick-start guide. For more detailed guide to locale content, check out the locale data documentation.

All of your site's region-specific content is set up in YAML files which live within the /src/locales/ directory. This content is further segmented into a globals directory as well as page-specific directories. Each of the filenames within these directories should match the locale config strings you've set up in the previous section. Here's an example file tree:

.
└── src/
    └── locales/
        ├── globals/
        │   ├── en.yml
        │   ├── es.yml
        │   └── fr.yml
        ├── home/
        │   ├── en.yml
        │   ├── es.yml
        │   └── fr.yml
        └── about/
            ├── en.yml
            ├── es.yml
            └── fr.yml

Global data

To add global locale data such as navigation items, headers, and footers; create and edit the appropriate YAML files under /src/locales/globals as needed. Ensure that YAML properties are consistent across all languages, unless certain locales should intentionally exclude information. Your filenames must match your locale config strings. For example, if your default locale is "en", the filename for English "global" locale data should be en.yml. Below are examples of two global locale files. We'll go over using the data at the end of this section. Here are two example global locale files for "en" and "fr":

/src/locales/globals/en.yml

# English!

meta:
  title: My Cool Web App
  description: The site-wide meta description.
  og_alt: Description of the og image.

header: My Project Name

footer: © Your Company Name.

/src/locales/globals/fr.yml

# Français !

meta:
  title: Mon application Web cool
  description: La méta description à l'échelle du site.
  og_alt: Description de l'image og.

header: Nom de mon projet

footer: © Le nom de votre entreprise.

Page-level data

To add page-specific locale data, create and edit the appropriate YAML files under /src/locales/<page-name>/ (where <page-name> is the directory name of your page, as it exists in your pages directory). Ensure that YAML properties are consistent across languages, unless certain locales should intentionally exclude information. Your filenames must match your locale config strings. For example, if your default locale is "en", the filename for English page data should be en.yml. Below are examples of two page-level locale files. We'll go over using the data at the end of this section. Here are two example page-level locale files for "en" and "fr":

/src/locales/home/en.yml

# English!

meta:
  title: My Cool Web App | Homepage
  description: The homepage-specific meta description.

title: My homepage
body: Lorem ipsum something, something. Irure sunt exercitation Lorem anim nostrud non ipsum fugiat aute. Reprehenderit ullamco aliqua dolore irure laboris. Officia nulla exercitation voluptate elit. Sit eiusmod nostrud reprehenderit Lorem veniam. Esse irure proident ea duis consectetur fugiat proident mollit mollit. Aliqua labore nostrud commodo laboris officia ullamco aliqua pariatur ex in reprehenderit magna. Cupidatat consequat labore mollit et anim veniam anim.

/src/locales/home/fr.yml

# Français !

meta:
  title: Mon application Web cool | Accueil
  description: La méta description spécifique à la page d'accueil.

title: Ma page d'accueil
body: Lorem ipsum quelque chose, quelque chose. Occaecat fugiat do sit id incididunt qui. Voluptate consectetur elit et enim ut sint excepteur dolore culpa laborum veniam eu ipsum. Non deserunt aliquip consectetur ut sunt nostrud labore officia labore. Incididunt eiusmod consectetur id aute anim dolor ipsum ullamco ex consequat esse fugiat. Excepteur ad sit tempor voluptate commodo. Ea labore veniam ea do. Aliqua non consequat ipsum irure id ipsum cillum laboris non reprehenderit culpa consequat.

Getting locale data into your components

The useLocale hook will allow you to retrieve locale information from within any functional React component. Data available includes globals, page data, the locale string, and more. Check out the useLocale documentation for more.

Global data example:

import { useLocale } from "@local/hooks";

const Footer = ({ children }) => {
  const { globals } = useLocale();

  return (
    <footer>
      <p>{globals.footer}</p>
    </footer>
  );
};

export default Footer;

Page and global data example:

import { useLocale } from "@local/hooks";

const HomeLayout = ({}) => {
  const { locale, page, globals } = useLocale()

  console.log(locale) // logs "en", or whichever locale string you're viewing.

  return (
    <header>{globals.header}</header>

    <main>
      <h1>{page.title}</h1>
      <p>{page.body}</p>
    </main>
  );
};

export default HomeLayout;