# @citychallenge/gatsby-plugin-intl

> Gatsby plugin to add react-intl onto a site

Latest version **0.4.0** (published 2020-05-22) · MIT license · 0 weekly downloads

## Install

```sh
npm install @citychallenge/gatsby-plugin-intl
pnpm add @citychallenge/gatsby-plugin-intl
yarn add @citychallenge/gatsby-plugin-intl
bun add @citychallenge/gatsby-plugin-intl
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.4.0 |
| Published | 2020-05-22 |
| First published | 2020-05-22 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 6 |
| Unpacked size | 23.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 316 |
| Author | Daewoong Moon |
| Maintainers | citychallenge-boy |
| Keywords | gatsby, gatsby-plugin, gatsby-plugin-intl, i18n, intl, react-intl |

## Links

- npm: https://www.npmjs.com/package/@citychallenge/gatsby-plugin-intl
- Repository: https://github.com/wiziple/gatsby-plugin-intl
- Issues: https://github.com/wiziple/gatsby-plugin-intl
- npm.io page: https://npm.io/package/@citychallenge/gatsby-plugin-intl

## Dependencies (6)

- [intl](https://npm.io/package/intl.md) ^1.2.5
- [react-intl](https://npm.io/package/react-intl.md) ^3.12.0
- [browser-lang](https://npm.io/package/browser-lang.md) ^0.1.0
- [@babel/runtime](https://npm.io/package/@babel/runtime.md) ^7.8.4
- [@formatjs/intl-pluralrules](https://npm.io/package/@formatjs/intl-pluralrules.md) ^1.5.2
- [@formatjs/intl-relativetimeformat](https://npm.io/package/@formatjs/intl-relativetimeformat.md) ^4.5.9

## Alternatives

- [messageformat](https://npm.io/package/messageformat.md) — 329.7K weekly downloads
- [@mintlify/scraping](https://npm.io/package/@mintlify/scraping.md) — 294.8K weekly downloads
- [@mintlify/previewing](https://npm.io/package/@mintlify/previewing.md) — 209.5K weekly downloads
- [@mintlify/prebuild](https://npm.io/package/@mintlify/prebuild.md) — 209.5K weekly downloads
- [@mintlify/link-rot](https://npm.io/package/@mintlify/link-rot.md) — 206.3K weekly downloads

## Recent versions

- 0.4.0 (latest) — 2020-05-22

## README

# gatsby-plugin-intl

Internationalize your Gatsby site.

## Features

- Turn your gatsby site into an internationalization-framework out of the box powered by [react-intl](https://github.com/yahoo/react-intl).

- Support automatic redirection based on the user's preferred language in browser provided by [browser-lang](https://github.com/wiziple/browser-lang).

- Support multi-language url routes in a single page component. This means you don't have to create separate pages such as `pages/en/index.js` or `pages/ko/index.js`.

## Why?

When you build multilingual sites, Google recommends using different URLs for each language version of a page rather than using cookies or browser settings to adjust the content language on the page. [(read more)](https://support.google.com/webmasters/answer/182192?hl=en&ref_topic=2370587)

## Starters

Demo: [http://gatsby-starter-default-intl.netlify.com](http://gatsby-starter-default-intl.netlify.com)

Source: [https://github.com/wiziple/gatsby-plugin-intl/tree/master/examples/gatsby-starter-default-intl](https://github.com/wiziple/gatsby-plugin-intl/tree/master/examples/gatsby-starter-default-intl)


## Showcase

- [https://picpick.app](https://picpick.app)
- [https://www.krashna.nl](https://www.krashna.nl) [(Source)](https://github.com/krashnamusika/krashna-site)
- [https://vaktija.eu](https://vaktija.eu)
- [https://anhek.dev](https://anhek.dev) [(Source)](https://github.com/anhek/anhek-portfolio)
- [https://pkhctech.ineo.vn](https://pkhctech.ineo.vn) [(Source)](https://github.com/hoangbaovu/gatsby-pkhctech)

*Feel free to send us PR to add your project.*

## How to use

### Install package

`npm install --save gatsby-plugin-intl`

### Add a plugin to your gatsby-config.js

```javascript
// In your gatsby-config.js
plugins: [
  {
    resolve: `gatsby-plugin-intl`,
    options: {
      // language JSON resource path
      path: `${__dirname}/src/intl`,
      // supported language
      languages: [`en`, `ko`, `de`],
      // language file path
      defaultLanguage: `ko`,
      // option to redirect to `/ko` when connecting `/`
      redirect: true,
    },
  },
]
```

### You'll also need to add language JSON resources to the project.

For example,

| language resource file | language |
| --- | --- |
| [src/intl/en.json](https://github.com/wiziple/gatsby-plugin-intl/blob/master/examples/gatsby-starter-default-intl/src/intl/en.json) | English |
| [src/intl/ko.json](https://github.com/wiziple/gatsby-plugin-intl/blob/master/examples/gatsby-starter-default-intl/src/intl/ko.json) | Korean |
| [src/intl/de.json](https://github.com/wiziple/gatsby-plugin-intl/blob/master/examples/gatsby-starter-default-intl/src/intl/de.json) | German |


### Change your components

You can use `injectIntl` HOC on any react components including page components.

```jsx
import React from "react"
import { injectIntl, Link, FormattedMessage } from "gatsby-plugin-intl"

const IndexPage = ({ intl }) => {
  return (
    <Layout>
      <SEO
        title={intl.formatMessage({ id: "title" })}
      />
      <Link to="/page-2/">
        {intl.formatMessage({ id: "go_page2" })}
        {/* OR <FormattedMessage id="go_page2" /> */}
      </Link>
    </Layout>
  )
}
export default injectIntl(IndexPage)
```
Or you can use the new `useIntl` hook.
```jsx
import React from "react"
import { useIntl, Link, FormattedMessage } from "gatsby-plugin-intl"

const IndexPage = () => {
  const intl = useIntl()
  return (
    <Layout>
      <SEO
        title={intl.formatMessage({ id: "title" })}
      />
      <Link to="/page-2/">
        {intl.formatMessage({ id: "go_page2" })}
        {/* OR <FormattedMessage id="go_page2" /> */}
      </Link>
    </Layout>
  )
}
export default IndexPage
```


## How It Works

Let's say you have two pages (`index.js` and `page-2.js`) in your `pages` directory. The plugin will create static pages for every language.

file | English | Korean | German | Default*
-- | -- | -- | -- | --
src/pages/index.js | /**en** | /**ko** | /**de** | /
src/pages/page-2.js | /**en**/page-2 | /**ko**/page-2 | /**de**/page-2 | /page-2

**Default Pages and Redirection**

If redirect option is `true`, `/` or `/page-2` will be redirected to the user's preferred language router. e.g) `/ko` or `/ko/page-2`. Otherwise, the pages will render `defaultLangugage` language. You can also specify additional component to be rendered on redirection page by adding `redirectComponent` option.


## Plugin Options

Option | Type | Description
-- | -- | --
path | string | language JSON resource path
languages | string[] | supported language keys
defaultLanguage | string | default language when visiting `/page` instead of `ko/page`
redirect | boolean | if the value is `true`, `/` or `/page-2` will be redirected to the user's preferred language router. e.g) `/ko` or `/ko/page-2`. Otherwise, the pages will render `defaultLangugage` language.
redirectComponent | string (optional) | additional component file path to be rendered on with a redirection component for SEO.


## Components

To make it easy to handle i18n with multi-language url routes, the plugin provides several components.

To use it, simply import it from `gatsby-plugin-intl`.

Component | Type | Description
-- | -- | --
Link | component | This is a wrapper around @gatsby’s Link component that adds useful enhancements for multi-language routes. All props are passed through to @gatsby’s Link component.
navigate | function | This is a wrapper around @gatsby’s navigate function that adds useful enhancements for multi-language routes. All options are passed through to @gatsby’s navigate function.
changeLocale | function | A function that replaces your locale. `changeLocale(locale, to = null)`
IntlContextConsumer | component | A context component to get plugin configuration on the component level.
injectIntl | component | https://github.com/yahoo/react-intl/wiki/API#injection-api
FormattedMessage | component | https://github.com/yahoo/react-intl/wiki/Components#string-formatting-components
and more... | | https://github.com/yahoo/react-intl/wiki/Components


## License

MIT &copy; [Daewoong Moon](https://github.com/wiziple)

---
_Source: https://npm.io/package/@citychallenge/gatsby-plugin-intl · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._