Nationwide Polamorous Matrimony

    gatsby-plugin-i18n-l10n
    TypeScript icon, indicating that this package has built-in type declarations

    5.0.0 • Public • Published

    gatsby-plugin-i18n-l10n

    Codecov GitHub Workflow Status npm npm

    Providing i18n and l10n to Gatsby. Besides translating pages and Markdown files, you can also translate the slugs and paths and still link between translated sibling pages. Batteries like a language switcher component are included. The plugin is written in Typescript, has some tests and builts on these two dependencies:

    • react-intl: Wrapping the pages with a provider, which makes translation available throughout the app.

    Features

    • Generates translated versions of pages.
      • For example, if you have a page src/pages/about.tsx and the languages en-US and de-CH configured, then it will create an en-US and de-CH version of this page. Via the page context of the translated pages, you get to know the locale.
    • Adds fields on MarkdownRemark and Mdx nodes.
    • Puts prefixes into the page paths, but not when it's the default locale.
    • Picks up locale from Markdown file names and provides it via custom fields in GraphQL.
      • It works with gatsby-transformer-remark and gatsby-plugin-mdx.
    • Makes it easy to navigate between the translations of a page.
    • Sets meta tags to provide locale information to crawlers and other machines.
    • Provides useful components like <LocalizedLink> and <LanguageSwitcher>.
    • Helps to translate paths, while keeping the possibility to navigate between the translations of a page.

    Usage

    1. Make sure the peer dependencies "gatsby": "^4.x" and "react-intl": "^6.x" are dependencies of your Gatsby project.

    2. Install the plugin with npm install gatsby-plugin-i18n-l10n or yarn add gatsby-plugin-i18n-l10n.

    3. Load and configure the plugin from your gatsby-config.js or gatsby-config.ts:

      {
        resolve: `gatsby-plugin-i18n-l10n`,
        options: {
          // IETF BCP 47 language tag: default locale, which won't be prefixed
          defaultLocale: `de-CH`,
          // string: absolute site url
          siteUrl: `https://example.com`,
          // locales[]: all locales, which should be available
          locales: [
            {
              // IETF BCP 47 language tag of this language
              locale: `en-US`,
              // string: prefix for this language, which will be used to prefix the url, if it's not the default locale
              prefix: `en`,
              // object: mapping of given urls (by filename) to translated urls, if no mapping exists, given url will be used
              slugs: {},
              // object: this messages will be handed over to react-intl and available throughout the website
              messages: {
                "language": "English"
              },
            },
            // another language
            {
              locale: `de-CH`,
              prefix: `de`,
              slugs: {
                '/products': '/produkte',
                '/products#donut-filled-with-jam': '/produkte#berliner',
                '/services/software-development': '/dienstleistungen/softwareentwicklung'
              },
              messages: {
                "language": "Deutsch"
              },
            },
          ],
          // omit certain path segments (relative directories)
          // be careful not to cause path collisions
          pathBlacklist: [
            '/pages' // /pages/products/gummibears becomes /products/gummibears
          ]
        },
      }

    <LanguageSwitcher>

    With the built-in <LanguageSwitcher> component, as user can change between the locales. With resolveLanguageName the language names can be provided to the component.

    <LanguageSwitcher resolveLanguageName={(locale) => intl.formatMessage({ id: `languages.${locale}` })} />

    createPage()

    When you create pages programmatically with createPage() by default the page will only try to set the locale and prefix to the context. With the following options you can instruct the plugin to internationalize the context further:

    • referTranslations: string[]: Refers translations for given locales.
    • adjustPath: boolean: Add locale prefix and replaces slugs.

    Alternatives

    Install

    npm i gatsby-plugin-i18n-l10n

    DownloadsWeekly Downloads

    30

    Version

    5.0.0

    License

    MIT

    Unpacked Size

    79.2 kB

    Total Files

    48

    Last publish

    Collaborators

    • openscript