Gatsby Theme ThePuzzlers Intl

This theme extends gatsby-plugin-react-intl. It is helpful to go through their docs as well to understand the set up: https://www.npmjs.com/package/gatsby-plugin-react-intl.

Getting Started

1. Install the gatsby theme

    $ yarn add gatsby-theme-thepuzzlers-intl

2. Add to list of plugins in the gatsby-config file and add the required theme options. Below is an example of the config for german and english pages.

    module.exports = {
        plugins: [{
            resolve: 'gatsby-theme-thepuzzlers-intl',
            options: {
                // react-intl Plugin Options
                path: `${__dirname}/src/intl`, 
                languages: ['en', 'de'],  
                redirect: true,
                // ThePuzzlers Theme Options
                locales: {
                    default: 'en',
                    translations: [{ pathPrefix: 'de', hreflang: 'de' }]
                },
                translatedPaths: [
                    { default: 'privacy-policy', de: 'datenschutz' },
                    { default: 'legal', de: 'impressum', en: 'legal-terms' }
                ]           
                
            }
        }]
    }

3. Add language JSON resources to the src/intl directory. The file name should be the corresponding language code.

src/intl/en.json

    {
        "title": "Gatsby English", 
        "hello": "Hi people",
        "welcome": "Welcome to your new Gatsby site.",
        "title_page2": "Page two",
        "hello_page2": "Hi from the second page", 
        "go_page2": "Go to page 2",
    }

src/intl/de.json

    {
        "title": "Gatsby Deutsch", 
        "hello": "hallo Leute",
        "welcome": "Willkommen auf Ihrer neuen Gatsby-Site.",
        "title_page2": "Seite zwei",
        "hello_page2": "Hallo von der zweiten Seite",
        "go_page2": "Gehen Sie zu Seite 2", 
    }

Theme Options

ThePuzzlers Theme Options

| Option | Value | Description | Required | | --------------- | ---------------- | ------------------------------------------------------------ | -------- | | locales | Object | Specifies the default locale, as well as the pathPrefix and hreflang of the other supported languages. | Yes | | translatedPaths | Object[] | This is used to get the translation of the page slug name. | Yes | | wrapProvider | Boolean | Default is true. If true, it will wrap the intl providers at the root element. If false, it will not and you are responsible for adding it. | No | | secondPath | String | This option is used to combine the translation messages. Add the path to the second translation dir. | No |

Plugin Options from gatsby-plugin-intl

| Option | Value | Description | Required | | --------------- | ---------------- | ------------------------------------------------------------ | -------- | | path | String | The Language JSON resource path | Yes | | languages | String[ ] | List of the supported languages. Ex. languages: ["en", "de"] | Yes | | redirect | Boolean | Option to redirect to /en when connecting /. Default is false. | No |

Dev Tools

Packages needed for extraction tools

If you are adding gatsby-theme-thepuzzlers-intl these are the packages you can add in order to extract and compile tranlsation messages.

1. Install Packages

yarn add --dev @babel/core @formatjs/cli babel-plugin-formatjs react-intl-translations-manager

2. Add babel configuration

// babel.config.json
{
  "plugins": [
    [
      "formatjs",
      {
        "idInterpolationPattern": "[sha512:contenthash:base64:6]",
        "ast": true
      }
    ]
  ],
  "presets": [
    [
      "babel-preset-gatsby",
      {
        "targets": {
          "browsers": [">0.25%", "not dead"]
        }
      }
    ]
  ]
}

3. Add translationRunner.js: This is to config react-intl-translations-manager

const manageTranslations = require('react-intl-translations-manager').default;

manageTranslations({
  messagesDirectory: 'intl/messages',
  translationsDirectory: 'intl/',
  languages: ['en', 'de'],
  singleMessagesFile: true,
  overrideCoreMethods: {
    provideExtractedMessages: () => {
      const extractedMessages = require('./intl/messages/messages.json');

      // Maps extracted messages to the return value structure they want
      return [
        {
          descriptors: Object.entries(extractedMessages).map((entry) => ({
            id: entry[0],
            defaultMessage: entry[1].defaultMessage
          }))
        }
      ];
    }
  }
});

4. Add scripts

  "scripts": {
    "extract": "formatjs extract \"src/**/*.js*\" --out-file intl/messages/messages.json --flatten --id-interpolation-pattern '[sha512:contenthash:base64:6]'",
    "compile": "node ./translationRunner.js"
  },

How To Extract & Compile translations

1. Run yarn extract command to extract all the translations within src/ folder
2. Run yarn compile command to generate updated language json files (ie. en.json & de.json)

Exported helper functions

useRevertPathToDefaultLocale

A hook used to revert any translations or prefixes added to a path.

Important note: The returned reverted path does not always equal the path of the default locale. Sometimes the default locale might have a translation configured. Therefore you should always use this hook in combination with the useLocalizePath hook when creating e.g. a link to navigate to.

Arguments

| Arg name | Value | Description | Required | | --------------- | ---------------- | ------------------------------------------------------------ | -------- | | pathToRevert | String | The path that you want to strip of all translations and path prefixes. | Yes |

Example usage

import { useRevertPathToDefaultLocale } from `gatsby-theme-thepuzzlers-intl`;

const MyComponent = () => {
  const basePath = useRevertPathToDefaultLocale('/de/datenschutz')

  return (
    <div />
  )
}

useLocalizePath

A hook used to revert any translations or prefixes added to a path.

Arguments

| Arg name | Value | Description | Required | | --------------- | ---------------- | ------------------------------------------------------------ | -------- | | path | String | The base path (which equal the name of the page in the pages directory), that you want to localize. | Yes | | locale | String | Locale you want to localize your component to. | Yes |

Example usage

import { useLocalizePath } from `gatsby-theme-thepuzzlers-intl`;

const MyComponent = () => {
  const localizedPath = useLocalizePath('privacy-policy', 'de')  // '/de/datenschutz'

  return (
    <button onClick={() => navigate(localizedPath)} />
  )
}