# @shopify/i18next-shopify

> i18nFormat plugin to use Shopify's translation format with i18next

Latest version **0.2.11** (published 2025-02-06) · MIT license · 0 weekly downloads

## Install

```sh
npm install @shopify/i18next-shopify
pnpm add @shopify/i18next-shopify
yarn add @shopify/i18next-shopify
bun add @shopify/i18next-shopify
```

## Health

**Score 45/100 (D)** — status: maintenance-mode.

Positive: has types; esm support; no vulnerabilities; has provenance; high quality score.

Warnings: low downloads; pre 1.0.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.2.11 |
| Published | 2025-02-06 |
| First published | 2023-05-01 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 118.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| Author | Michael Overmeyer |
| Maintainers | shopify-admin, shopify-dep, mishsmelle, netlohan, pmoloney89, maryharte, jaimie.rockburn, jaykay101 |
| Keywords | i18next, i18next-format |

## Links

- npm: https://www.npmjs.com/package/@shopify/i18next-shopify
- Repository: https://github.com/Shopify/i18next-shopify
- Issues: https://github.com/Shopify/i18next-shopify/issues
- npm.io page: https://npm.io/package/@shopify/i18next-shopify

## Dependencies (1)

- [globals](https://npm.io/package/globals.md) ^15.9.0

## Alternatives

- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads

## Recent versions

- 0.2.11 (latest) — 2025-02-06
- 0.2.10 — 2024-11-25
- 0.2.9 — 2023-09-25
- 0.2.8 — 2023-09-14
- 0.2.7 — 2023-09-13
- 0.2.6 — 2023-09-13
- 0.2.5 — 2023-09-13
- 0.2.4 — 2023-09-08
- 0.2.3 — 2023-06-07
- 0.2.2 — 2023-06-05
- 0.2.1 — 2023-05-30
- 0.2.0 — 2023-05-24
- 0.1.1 — 2023-05-18
- 0.1.0 — 2023-05-10
- 0.0.4 — 2023-05-09
- … 2 more at https://npm.io/package/@shopify/i18next-shopify/versions

## README

# `@shopify/i18next-shopify`

This package is an `i18nFormat` plugin for the [i18next](https://www.i18next.com/) library. It allows developers to use the same format used by Shopify [apps](https://shopify.dev/docs/apps/checkout/best-practices/localizing-ui-extensions#how-it-works) and [themes](https://shopify.dev/docs/themes/architecture/locales/storefront-locale-files#usage) for localization.

Key features include:
* Variable interpolation with both single `{}` and double `{{}}` curly brace mustache formats
* Pluralization as nested keys
  * E.g. `{ "keyWithCount": { "one": "value" } }` instead of `{ "keyWithCount_one": "value" }`
* Variable interpolation with React components as replacement values
  * E.g. `t("key", { businessName: <strong>Shopify</strong> })`
* Ordinal pluralization using the interpolation variable `ordinal` as number (e.g. `t("key", { ordinal: 1 })`) or using the interpolation variable `ordinal` as boolean and `count` as number (e.g. `t("key", { ordinal: true, count: 1 })`)
  * NOTE: When `ordinal` is explicitly set to `0` and `count` is also explicitly set, the plugin will treat this as cardinal pluralization (e.g. `t("key", { count: 1, ordinal: 0 }`))

## Table of contents
[Getting Started](#getting-started)\
[Example](#example)\
[License](#license)\
[Contributing](#contributing)\
[References](#references)

## Getting started

### Add the package
```
$ npm install @shopify/i18next-shopify
```
or
```
$ yarn add @shopify/i18next-shopify
```

### Configure i18next to use this plugin

> **Warning**
> The [`Intl.PluralRules` API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/PluralRules) is required for this plugin's plural handling.
> If your target environments do not support this API, you may need to [polyfill](https://github.com/eemeli/intl-pluralrules) it.
> This plugin's plural handling is not compatible with i18next's fallback to JSON format v3 plural handling.

```js
import i18next from "i18next";
import ShopifyFormat from "@shopify/i18next-shopify";

i18next.use(ShopifyFormat).init(i18nextOptions);
```

## Example

```js
import i18next from "i18next";
import ShopifyFormat from "@shopify/i18next-shopify";

i18next.use(ShopifyFormat).init({
  lng: "en",
  resources: {
    en: {
      translation: {
        hello: "Hello {{casualName}}!",
        products: {
          "0": "I have no products.",
          "1": "I have a single product.",
          one: "I have {{count}} product.",
          other: "I have {{count}} products.",
        },
      },
    }
  }
});

i18next.t("hello", { casualName: "Shopify" }); // -> Hello Shopify!
i18next.t("products", { count: 2 }); // -> I have 2 products!
```

## License

[MIT](https://github.com/Shopify/i18next-shopify/blob/main/LICENSE)

## Contributing

Want to make i18next-shopify better for everyone? We'd love your help!  Please start off by reading our [Code of Conduct](https://github.com/Shopify/i18next-shopify/blob/main/CODE_OF_CONDUCT.md).

### Report a bug

Bugs are tracked at GitHub issues.  Search open issues to see if someone else has reported a similar bug. If it's something new, open an issue. We'll use the issue to have a conversation about the problem you want to fix.  You may also suggest features using GitHub issues.

When creating a new issue, please ensure the issue is clear and include additional details to help maintainers reproduce it:

Use a clear and descriptive title for the issue to identify the problem.
- Describe the exact steps which reproduce the problem in as many details as possible.
- Provide specific examples to demonstrate the steps. Include links to files, or copy/pasteable snippets. If you're providing snippets in the issue, use Markdown code blocks.
- Describe the behavior you observed after following the steps and point out what exactly is the problem with that behavior.
- Explain which behavior you expected to see instead and why.
- Include screenshots and animated GIFs where possible.

### Contributing Code

Useful commands:
- `yarn install` to install development dependencies
- `yarn test` to run the test suite
- `yarn tdd` to run tests after files are updated
- `yarn lint` to run the linter
- `yarn changeset` to generate a changeset

How to contribute:
- Open a PR with your contribution.  Fill out all applicable sections of the [PR template](https://github.com/Shopify/i18next-shopify/blob/main/.github/pull_request_template.md)
- Include a [changeset](https://github.com/changesets/changesets) in your pull request. This helps us keep the changelog and version accurate.
  - If you believe an empty changeset is warranted and appropriate, one can be generated by running `yarn changeset add --empty`
- Before you can merge your pull request, you must sign Shopify's [Contributor License Agreement (CLA)](https://cla.shopify.com/).

Thank you for your interest in contributing!

## References

* [Shopify theme storefront locale files](https://shopify.dev/docs/themes/architecture/locales/storefront-locale-files#usage)
* [Shopify theme schema locale files](https://shopify.dev/docs/themes/architecture/locales/schema-locale-files)
* [Shopify app locale files](https://shopify.dev/docs/apps/checkout/best-practices/localizing-ui-extensions#how-it-works)

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