Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/alexanderwallin/lioness

🐯 A React library for efficiently implementing Gettext localization
https://github.com/alexanderwallin/lioness

gettext i18n l10n localization react translation

Last synced: 4 days ago
JSON representation

🐯 A React library for efficiently implementing Gettext localization

Awesome Lists containing this project

README 

        


  

  


  


  Lioness

  


  npm version 




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



It utilises [`node-gettext`](https://github.com/alexanderwallin/node-gettext) as translations tool, but this ought to be modularized in the future.



```js

}

  listLink={}

/>

// items.length === 1 => Du har en grej, kolla in den här.

// items.length === 7 => Du har 7 grejer, kolla in dem här.

```



## Table of contents



* [Features](#features)

* [Installation](#installation)

* [Usage](#usage)

  * [Using ``](#using-t-)

  * [Using `withTranslators(Component)`](#using-withtranslatorscomponent)

  * [Locale switching](#locale-switching)

* [API](#api)

* [Contributing](#contributing)

* [See also](#see-also)



## 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](#locale-switching) on the fly



## Installation



```sh

npm install --save lioness



# ...or the shorter...

npm i -S lioness

```



## Usage



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



```js

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 (

    

      


        
Potato inventory


        {/* => 
Potatisinventarie
 */}



        

        {/* => Kära Ragnhild, det finns 2 potatisar kvar */}



        }

        />

        {/* => Köp mer potatis här! */}

      


    

  )

}



ReactDOM.render(

  ,

  document.querySelector('.app-root')

)

```



### Using ``



`` 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`.



```js

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 {message}

}



export default withTranslators(PotatoNotification)

```



### Via [`babel-plugin-react-gettext-parser`](http://github.com/alexanderwallin/babel-plugin-react-gettext-parser)



```js

// .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. `` will trigger a re-render of all `` 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 ``



| Gettext      | `withTranslations` | ``       |

| ------------ | ------------------ | ------------- |

| 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 ``.



* #### `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.



### ``



A higher-order component that provides the translation functions and state to `` through context.



**Props:**



* `messages` – An object containing translations for all languages. It should have the format created by [gettext-parser](https://github.com/smhg/gettext-parser)

* `locale` – The currently selected locale (which should correspond to a key in `messages`)

* `gettextInstance` - A custom [node-gettext](https://github.com/alexanderwallin/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 `` sends it to the translation function. One use case is normalising strings when something like [`prettier`](https://github.com/prettier/prettier) puts child content in `` 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](https://github.com/alexanderwallin/node-gettext) - A JavaScript implementation of Gettext.

* [gettext-parser](https://github.com/smhg/gettext-parser) – A parser between JSON and .po/.mo files. The JSON has the format required by this library.

* [react-gettext-parser](https://github.com/laget-se/react-gettext-parser) – A utility that extracts translatable content from JavaScript code.

* [narp](https://github.com/laget-se/narp) – A workflow utility for extracting, uploading, downloading and integrating translations.