npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

lioness

v0.2.19

Published

A React library for efficiently implementing Gettext localization

Downloads

1,269

Readme

Lioness is a React library for efficiently implementing Gettext localization in your app with little effort.

It utilises node-gettext as translations tool, but this ought to be modularized in the future.

<T
  message="You have one thingy, {{ itemLink:check it out }}"
  messagePlural="You have {{ count }} thingies, {{ listLink:check them out }}"
  count={items.length}
  itemLink={<a href={`/thingies/${items[0].id}`} />}
  listLink={<a href="/thingies" />}
/>
// items.length === 1 => Du har en grej, <a href="/thingies/281">kolla in den här<a/>.
// items.length === 7 => Du har 7 grejer, <a href="/thingies">kolla in dem här<a/>.

Table of contents

Features

  • Context and plural
  • String interpolation using a {{ variable }} style syntax
  • Component interpolation with translatable child content using a {{ link:Link text here }} style syntax
  • Locale switching on the fly

Installation

npm install --save lioness

# ...or the shorter...
npm i -S lioness

Usage

This is an example app showing how to translate some text:

import React from 'react'
import ReactDOM from 'react-dom'
import { LionessProvider, T } from 'lioness'

// messages.json is a JSON file with all translations concatenated into one.
// The format must conform to what node-gettext expects.
//
// See https://github.com/alexanderwallin/node-gettext#Gettext+addTranslations
import messages from './translations/messages.json'

function App({ name, numPotatoes }) {
  return (
    <LionessProvider
      messages={messages}
      locale="sv-SE"
      debug={/* true | false | null */}
    >
      <div className="App">
        <h1><T>Potato inventory</T></h1>
        {/* => <h1><span>Potatisinventarie</span></h1> */}

        <T
          message="Dear {{ name }}, there is one potato left"
          messagePlural="Dear {{ name }}, there are {{ count }} potatoes left"
          count={numPotatoes}
          name={name}
        />
        {/* => <span>Kära Ragnhild, det finns 2 potatisar kvar</span> */}

        <T
          message="By more potatoes {{ link:here }}!"
          link={<a href="http://potatoes.com/buy" />}
        />
        {/* => <span>Köp mer potatis <a href="http://potatoes.com/buy">här</a>!</span> */}
      </div>
    </LionessProvider>
  )
}

ReactDOM.render(
  <App name="Ragnhild" numPotatoes={Math.round(Math.random() * 3))} />,
  document.querySelector('.app-root')
)

Using <T />

<T /> exposes a set of props that make it easy to translate and interpolate your content. Being a React component, it works perfect for when you are composing your UI, like with the example above.

Using withTranslators(Component)

Sometimes, you will need to just translate and interpolate pure strings, without rendering components. To do this you can hook up your components with translator functions using the withTranslators(Component) composer function.

withTranslators(Component) will provide any component you feed it with a set of translator functions as props. Those props are: t, tn, tp, tnp, tc, tcn, tcp and tcnp.

import { withTranslators } from 'lioness'

function PotatoNotification({ notificationCode, t }) {
  let message = ''

  if (notificationCode === 'POTATOES_RECEIVED') {
    message = t(`You have received potatoes`)
  } else if (notificationCode === 'POTATOES_STOLEN') {
    message = t(`Someone stole all your potatoes :(`)
  }

  return <span>{message}</span>
}

export default withTranslators(PotatoNotification)

Via babel-plugin-react-gettext-parser

// .babelrc
{
  ...
  "plugins": [
    ["react-gettext-parser", {
      "output": "gettext.pot",
      "funcArgumentsMap": {
        "tc": ["msgid", null],
        "tcn": ["msgid", "msgid_plural", null, null],
        "tcp": ["msgctxt", "msgid", null],
        "tcnp": ["msgctxt", "msgid", "msgid_plural", null, null],

        "t": ["msgid"],
        "tn": ["msgid", "msgid_plural", null],
        "tp": ["msgctxt", "msgid"],
        "tnp": ["msgctxt", "msgid", "msgid_plural", null]
      },
      "componentPropsMap": {
        "T": {
          "message": "msgid",
          "messagePlural": "msgid_plural",
          "context": "msgctxt",
          "comment": "comment"
        }
      }
    }]
  ]
  ...
}

Locale switching

Lioness makes it possible to change locale and have all the application's translations instantly update to those of the new locale. <LionessProvider> will trigger a re-render of all <T> components and components wrapped in withTranslators() whenever its locale or messages props change.

Note: For performance reasons, and in favour of immutability, this check is done using shallow equality, which means you need to pass an entirely new object reference as messages for it to trigger the re-render. If this is an issue for you, simply make sure you create a new object when you get new messages, for instace by using something like messages = Object.assign({}, messages).

API

The following table indicates how gettext strings map to parameters in withTranslations and props for <T />

| Gettext | withTranslations | <T /> | | ------------ | ------------------ | ------------- | | msgctxt | context | context | | msgid | message | one | message | | msgid_plural | other | messagePlural |

withTranslations(Component)

Provides Component with the lioness context variables as props. These are locale, t, tn, tp, tnp, tc, tcn, tcp and tcnp.

As a little helper, here's what the letters stand for:

| Letter | Meaning | Parameters | | ------ | --------------------------------- | ----------------------- | | t | translate a message | message | | c | ...with injected React components | - | | n | ...with pluralisation | one, other, count | | p | ...in a certain gettext context | context |

  • locale

    The currently set locale passed to <LionessProvider />.

  • t(message, scope = {})

    Translates and interpolates message.

  • tn(one, other, count, scope = {})

    Translates and interpolates a pluralised message.

  • tp(context, message, scope = {})

    Translates and interpolates a message in a given context.

  • tnp(context, one, other, count, scope = {})

    Translates and interpolates a pluralised message in a given context.

  • tc(message, scope = {})

    Translates and interpolates a message.

  • tcn(one, other, count, scope = {})

    Translates and interpolates a pluralised message.

  • tcp(context, message, scope = {})

    Translates and interpolates a message in a given context.

  • tcnp(context, one, other, count, scope = {})

    Translates and interpolates a plural message in a given context.

<LionessProvider />

A higher-order component that provides the translation functions and state to <T /> through context.

Props:

  • messages – An object containing translations for all languages. It should have the format created by gettext-parser
  • locale – The currently selected locale (which should correspond to a key in messages)
  • gettextInstance - A custom node-gettext instance. If you provide the messages and/or local props they will be passed on to this instance.
  • transformInput – A function (input: String) => String that you can use to transform a string before <T /> sends it to the translation function. One use case is normalising strings when something like prettier puts child content in <T /> on new lines, with lots of indentation. The default is a function that simply returns the input as is.

Contributing

All PRs that passes the tests are very much appreciated! 🎂

See also

  • node-gettext - A JavaScript implementation of Gettext.
  • gettext-parser – A parser between JSON and .po/.mo files. The JSON has the format required by this library.
  • react-gettext-parser – A utility that extracts translatable content from JavaScript code.
  • narp – A workflow utility for extracting, uploading, downloading and integrating translations.