react-translations
v1.0.0
Published
modern gettext-style translations for React
Downloads
98
Maintainers
Readme
react-translations
Modern translations for React. Lightweight and isomorphic app friendly.
Translation Format
This library uses gettext as the translation style, and thus relies on PO file format for storing translations. Gettext has been battle tested, and the PO format is very familiar to translators. The system is simple to use and allows the developer to continue building out UIs in the English language, with an almost complete isolation to the rest of the internationalization process. Read more information here.
Example
A complete example client (React) and server (Express.JS) setup, with build chain (Webpack & Gulp), is available at react-translations-demo!
Usage
Component Verbose Style
import { Message } from 'react-translations'
Singular form
<Message id="Hello World!" />
Singular form with context
<Message id="Flag" context="Physical object" />
Plural form
<Message
id="You have one cat!"
idPlural="You have {numCats} cats!"
count={1}
numCats="1" />
Plural form with context and translator comment
<Message
id="You have {numCats} car!"
idPlural="You have {numCats} cars!"
numCats="1,000"
count={1000}
context="Homepage"
comment="Here's a comment for the translator" />
Component Shortform Style
import { _, _n, _c, _nc, Message } from 'react-translations'
<Message i18n={_('You have one cat!, You have many cats!', 1)} />
...
Vanilla JS
import { _, _n, _c, _nc } from 'react-translations'
const someString = _('Hello World!')(locale)
Setup
Set the available translations on the client (and server if you perform SSR):
import { setMessages } from 'react-translations'
setMessages({ ... })
You want to set this before you perform any rendering. On the client this may be start of a webpack entry. On the server, during boot. The shape of this object is specific to Jed, which is what is used to do the gettext mapping. You can use tools to generate this format automatically (see FAQ).
Wrap your root React component with the provider:
import { LocaleProvider } from 'react-translations'
return <LocaleProvider locale={locale}><App/></LocaleProvider>
The user's locale (combination of language and region) must be provided and will be used to determine the translations based on one of the keys in the object passed to setMessages
earlier. How you detect a user's locale is completely up to you.
Placeholders
Placeholders like numCats
above can be standard JS types or React elements.
Note that count
can be used to determine plurality, and function as a placeholder. So if you don't care about additonal formatting of numbers, the above example could be simplified to:
<Message id="You have one cat!" idPlural="You have {count} cars!" count={1000} />
FAQ
- What can I use to extract strings from these components for translation?
You can use the babel plugin babel-extract-gettext to do an export into a PO
file format that translators are familiar with.
- How can I convert a
PO
file back intoJSON
to be used for this library?
You can use po2json to do the conversion.
- When/where should the above things run?
It depends on your build chain. If you are friendly with gulp, it can be used easily with gulp-po2json to do imports. Exports can be achieved with gulp-babel and the previously named babel plugin.
- Where can I see an example of how to support server rendering, build chain, <insert X>?
Check out react-translations-demo!
Acknowledgements
Thanks to the author of Jed. Not only for the library itself, but also for inspiration to continue driving internalization and translations forward in the JS community.