i18n

Internationalization (i18n), is the process of preparing your website to deal with more than just one language, and local configuration, in fact, internationalization, allows users from many locales can access your website, with their native languages, and configurations.

Engrafia supports i18n NextJs out of the box, it's really easy to configure, you need to add a list of locales, and some JSON files to put your translations.

Initial configuration

Engrafia supports NextJs i18n by subpath and adds property lang in HTML tag automatically, which means that your website will have a better results with search engines, like Google.

next.config.js

Engrafia requires some configurations in the next.config.js file, it's necessary to add some locales in the i18n config, and the default locale/language:

js
module.exports = withEngrafia({
i18n: {
locales: ['en', 'pt'],
defaultLocale: 'en',
},
});

The below example, show you how to create a configuration considering just the language, if you want to specify the location, you can do that by adding the location abbreviation, for example; en-US.

  • en-US - English as spoken in the United States
  • nl-NL - Dutch as spoken in the Netherlands
  • nl - Dutch, no specific region

You can find the complete specification on w3schools.

Adding labels

When using internationalization in your Engrafia application, it is necessary to add some labels for custom pages, links, buttons, and sidebar category names. The right place to put it is in public/locales/your-locale-file.json, for example; public/locales/en.json

json
{
"description": "This is a description",
"link.docs": "Documentation",
"link.github": "Github",
"edit.content": "Edit this content",
"table.of.content": "Page content",
"search.placeholder": "Search..."
}

Sidebar is generated by the file system, which means that you can't edit the folder name, but you can add labels that match the folder names, when you decide to use internationalization in your Engrafia application, the Sidebar will look at your label file to find a key that matches with folder name.

If you create a folder named features, the sidebar will look for a features key in public/locales/your-language.json, if the sidebar can't find it, the folder name will be formatted to present a pretty category menu.

useTranslation

This hook is a simple way to bind a key by a label value, useTranslation should be used on pages like, home, 404, or another custom page.

jsx
import { useTranslation } from 'engrafia';
export default function Homepage() {
const t = useTranslation();
return <h1>{t('page.title')}</h1>;
}

If you have some doubts about how to configure i18n in NextJs applications, we recommend you to read the NextJS i18n docs: Next Doc

MD, and MDX contents

For md, and mdx files, you should create different files for every languages, for example:

mdx
engrafia-app
- pages
- docs
- page-examples.pt
- page-examples.en

Language selector

To select a language, the Engrafia template provides a language selector located on the top and right side of the screen.

seletor-idiomas