Nefariously Programmed Mecha

    react-polyglot-hooks
    TypeScript icon, indicating that this package has built-in type declarations

    0.5.0 • Public • Published

    React Polyglot Hooks

    Hooks for using Polyglot.js with React.

    npm Package Minified Size Min-zipped Size

    CircleCI Coverage Status Code Style Conventional Commits Dependabot Status Dependencies PeerDependencies DevDependencies

    Installation

    React Polyglot Hooks is available as an npm package.

    // with npm
    npm install react-polyglot-hooks
     
    // with yarn
    yarn add react-polyglot-hooks

    React is required as a peer dependency. Please install version 16.8.3 or later (minimum requirement for hooks).

    Usage

    React Polyglot Hooks offers 1 wrapper component: <I18n>, 2 hooks: useLocale and useT and 1 helper component: <T>. The hooks and the helper component have to be wrapped with the <I18n> component to work properly.

    Here is a quick example to get you started: First, wrap a parent component with <I18n> and provide locale and phrases.

    Parent.jsx

    import React from 'react';
    import { I18n } from 'react-polyglot-hooks';
    import Child from './Child';
     
    // ... or any ways to determine current locale
    const locale = window.locale || 'en';
     
    // You can put translations in separate files
    const phrases = {
      en: { hello: 'Hello, World!' },
      fr: { hello: 'Bonjour, Monde!' },
    };
     
    export default function Parent() {
      return (
        <I18n locale={locale} phrases={phrases[locale]}>
          <Child />
        </I18n>
      );
    }

    Then, in a child component, call the hooks:

    Child.jsx

    import React from 'react';
    import { T, useLocale } from 'react-polyglot-hooks';
     
    export default function Child() {
      const locale = useLocale(); // Current locale: "en"
      return (
        <React.Fragment>
          <span>{locale}</span>
          <T phrase="hello" />
        </React.Fragment>
      );
    }

    That's it! For more in-depth examples, check out the examples directory.

    Usage with TypeScript

    Types are baked in as the project is written in TypeScript.

    API

    <I18n>

    Provides i18n context to the T component and the hooks. Accepts all options supported by Polyglot.js.

    Props

    Prop Type Required Description
    children Node Any node(s) accepted by React.
    locale string Current locale, used for pluralization.
    phrases { [key: string]: string } Key-value pair of translated phrases, can be nested.
    allowMissing boolean Controls whether missing phrase keys in a t call is allowed.
    interpolation { prefix: string, suffix: string } Controls the prefix and suffix for an interpolation.
    onMissingKey (key: string, options: InterpolationOptions, locale: string) => string A function called when allowMissing is true and a missing key is encountered.
    pluralRules { pluralTypes: PluralTypes, pluralTypeToLanguages: PluralTypeToLanguages } Custom pluralization rules to be applied to change language(s) behaviour(s).

    <T>

    Renders a phrase according to the props.

    Props

    Props Type Required Description
    phrase string Key of the needed phrase.
    count number A number to be interpolated with smart_count.
    fallback string A fallback to be rendered if the phrase is missing.
    interpolations InterpolationOptions See InterpolationOptions below.

    useLocale

    Returns the current active locale (string).

    useT

    Returns a special function (t) which takes in parameters and returns a phrase.

    t(phrase, InterpolationOptions)

    Param Type Required Description
    phrase string Key of the needed phrase.
    InterpolationOptions number or { [key: string]: ReactNode } A number to be interpolated with smart_count, or a key-value pair to interpolate values into the phrase.

    For more details, please visit the documentation of Polyglot.js.

    Changelog

    The changelog is available here.

    License

    This project is licensed under the terms of the MIT License.

    Acknowledgements

    This project is developed to ease the use of Polyglot.js within React, and is highly influenced by react-polyglot.

    Install

    npm i react-polyglot-hooks

    DownloadsWeekly Downloads

    711

    Version

    0.5.0

    License

    MIT

    Unpacked Size

    27.2 kB

    Total Files

    22

    Last publish

    Collaborators

    • pmmmwh