Yuansa-i18n NPM

yuansa-i18n

Notice: This is an experimental package with no reliable testing so it may has unknown bugs. You are warmly welcomed to use it to test and report bugs~ Thank you!

A tool that helps you to auto config manage react-intl. By several simple configuration like "your locale file url", you will be able to use react-intl, no more frustrating contexts settings needed.

yuansa-i18n will enable you to:

Manage locales with hooks
Have fallbacks when Text's key is missing
Fetch texts conditionally and remotely
Cache user's locale preference in window.localStorage (Will use window.navigator.language as fallback locale if no defaultLocale found)

Get Started

Install yuansa-i18n by running the following command:

# if you use npm as your package manager, run:
npm install --save yuansa-i18n

# if you use yarn as your package manager, run:
yarn add yuansa-i18n

# if you use pnpm as your package manager, run:
pnpm add yuansa-i18n

But if you are using a monorepo, please refer to the document of your monorepo engine to get the right command.

Wrap your APP with I18nProvider from yuansa-i18n and pass your configuration to it:

import { FC } from "react";
import { I18nProvider } from "yuansa-i18n";
import { enUS, zhCN, esMX } from "@/locale";

const i18nConfig = {
  remoteI18nDictURLMap: {
    "en-US": "/locale/en-US.json",
    "zh-CN": "/locale/zh-CN.json",
    "es-MX": "/locale/es-MX.json",
  },
  localeI18nDictMap: {
    "en-US": enUS,
    "zh-CN": zhCN,
    "es-MX": esMX,
  },
  defaultLocale: "en-US",
};

const APP: FC = () => (
  <I18nProvider {...i18nConfig}>
    <MyAPP />
  </I18nProvider>
);

You can use i18n from yuansa-i18n or traditional intl from react-intl in your APP as you wish.

import { useIntl } from "react-intl";
import { useI18n } from "yuansa-i18n";

// Traditional `useIntl`
const ExampleA = () => {
  const intl = useIntl();

  return intl.formatMessage({ id: "example" });
};

// Get i18n states from `useI18n().i18n`
// You can also get `intl` from `useI18n()`
const ExampleB = () => {
  const { i18n, intl } = useI18n();
  const { locale, setLocale, isLoadingRemoteI18nDict } = i18n;

  return (
    <>
      <span>Current lang: {locale}</span>
      <button onClick={() => setLocale("zh-CN")}>
        {intl.formatMessage({
          id: isLoadingRemoteI18nDict ? "loading" : "change_lang",
        })}
      </button>
    </>
  );
};