This project was built with Gatsby.
yarn
yarn lint
yarn flow
yarn dev
This will start a local development server on port 8000
.
http://localhost:8000/
http://localhost:8000/___graphql
Running deploy
will deploy this project to github pages (if configured to do so).
yarn build
yarn deploy
Because content for this website is sourced both locally within the project and externally (such as GitHub for docs pages), there are a few moving parts to keep in mind.
/es/
or /fr/
en
). If no locale is provided, the default will be used.The project config is a json
file which contains certain attributes & meta data about a project, such as logo files, project description, section order, etc. Each project's docs
directory must contain one, or the project's docs will be skipped when the docs are sourced.
There are two optional (but highly recommended) project configurations possible regarding translations:
Let's break these down...
By using translated section names in doc frontmatter, the section names will already be translated. However the translated section names must still be ordered. This is achieved with a map-like object. The locale is the key, and the value is an array of translated section names in order:
// doc.config.json
{
"sectionOrder": ["Docs", "Interface", "Modules"], // <-- Default language section order
"sectionTranslations": {
"es": ["Docs", "Interfaz", "Modulós"] // <-- Section order for `es` locale
}
}
Similar to the Translated Section Order above, the project description must also be translated, and is done so with a map-like object. The locale is the key, and the value is the translated string:
// doc.config.json
{
"description": "The purser library is a...", // <-- Default language project description
"descriptionTranslations": {
"es": "La biblioteca de Purser es una..." // <-- Project description for `es` locale
}
}
locale
frontmatter, and this locale
must match one of the configured locales for the website.
locale
is one that the website is not yet configured with, it will be skipped when the docs are sourced.locale
frontmatter, it will be sourced and placed directly along-side the default (in this case, english) docs.Here's an example frontmatter for a purser
doc page configured for es
locale:
---
title: Visión General
section: Docs
order: 0
locale: es
---
... Doc content ...
The resulting slug for the above example would be /es/${docsSlugPrefix}/purser/docs-vision-general
Doc pages often link to each other, or to doc pages in other projects. Sometimes, other projects (or other doc pages within the same project, even) may not have the same language support. So the path to the related doc page should be locale-explicit when using an alternate language.
Here are the two ways links can be written in markdown docs:
/${slugifiedProjectName}/${slugifiedSection}-${slugifiedTitle}/
/${locale}/${slugifiedProjectName}/${slugifiedSection}-${slugifiedTitle}/
purser
doc page:---
title: Interfaz de la Billetera Común
section: Interfaz
order: 0
locale: es
---
[La Interfaz de la billetera común](/es/purser/interfaz-interfaz-de-la-billetera-comun/)
Note: When the
DocPage
template renders this, the links will be parsed and the parser will know to rewrite the url with thedocsSlugPrefix
injected. So the resulting path will be/es/${docsSlugPrefix}/purser/interfaz-interfaz-de-la-billetera-comun/
.
Trying to access a locale that isn't configured will result in a 404 response, even if doc pages are written for said locale. To enable a particular locale for the entire website, a few things need to happen:
react-intl
to Use New Localepages
Update the CONFIGURED_LOCALES
array in i18nConfig
to contain the new locale.
This tells both gatsby-plugin-i18n
and gatsby-transform-md-docs
about the new locale, and allows routing & doc page creation (for any docs with that specified locale in their frontmatter).
Add a LocaleConfig
object to the localeMessages
object in /src/modules/layouts/GlobalLayout/GlobalLayout.jsx
.
Create a messages file and import it, along with the correct language data set from react-intl
and provide those to the config object.
Here's an example with both en
and es
:
// GlobalLayout.jsx
import enLocaleData from 'react-intl/locale-data/en';
import esLocaleData from 'react-intl/locale-data/es';
import enMessages from '~i18n/en.json';
import esMessages from '~i18n/es.json';
const localeMessages: LocaleConfigs = {
en: {
messages: enMessages,
data: enLocaleData,
},
es: {
messages: esMessages,
data: esLocaleData,
},
};
This configures the locale data for the IntlProvider
, and helps set the locale from the url.
For each page (found in /src/pages/
), add a locale-specific version. This can simply export the same component as the default locale version - it's just required because of gatsby-plugin-i18n
's convention is such.
For example:
\_ pages
\_ index.js <-- This is the default version
\_ index.es.js <-- This is the `es` version