react-translated
A dead simple way to add complex translations in a React project 🌎🌍🌏
Features
- 💥 Data interpolation
- ☄ Component interpolation
- Ⓜ Markdown inline-manipulations
- 🔀 Custom manipulations, pluralizations, and grammar rules based on input-data
- ⚛ Component-level translation files (enables loading only required translations)
Example
Write this:
<Translate ="{difficulty} *translations* in React <ReactLogo>" = =/>
To render this:
Support
React DOM and React Native 🔥
Try
Play around with the library in your browser through the CodeSandbox.
Table of Contents
Installation
Whatever floats your boat:
Setup
Step 1: Create the translations file
Create a file that will contain a mapping of keys to the string in each language you support.
To keep things simple, use the strings of your default language as the key:
// translation.js 'Hi, World!': en: 'Hi, World!' fr: 'Bonjour le monde!' // ...
NOTE: There is no enforcement on the key used for a language. In these examples, 2-digit country codes (
en
,fr
, etc) are used. Decide on a convention and use that for all translations.
Provider
Step 2: Connect the Wrap your top-level component with the <Provider>
and set the translation
and language
props:
// index.js import Provider from 'react-translated'import translation from './translation'const App = <Provider ="en" => <MyApplicationRoot /> </Provider>
NOTE: The value of the
language
prop must be one of the keys used for a language defined in Step 1.
Step 3: Start translating
That is all!
Continue reading below to see how to handle the various translation scenarios.
Usage
The library can be imported in whatever way you find suitable:
<ReactTranslatedTranslate /*...*/ />
Or:
<Translate /*...*/ />
Translate
vs Translator
The Translate
component should always be used when the translation is rendered as a child component; such as buttons, paragraphs, headings, etc.
The Translator
component should only be used when the translation is needed as a string; such as placeholders, alternate text, etc.
Translation scenarios
- Static text
- Templated text
- Dynamically templated text
- Styled text
- Component within text
- Translated text as string (for text input placeholders)
Static text
This is pretty self-explanatory:
// translation.js 'Hi, World!': en: 'Hi, World!' fr: 'Bonjour le monde!' // any component file<Translate ='Hi, World!' />
Renders as:
Templated text
To use dynamic text, the text can be templated:
// translation.js 'Hi, {firstName}!': en: 'Hi, {firstName}!' fr: 'Salut {firstName}!' // any component file<Translate ='Hi, {firstName}!' = />
Renders as:
Dynamically templated text
Sometimes just dynamic text is not enough and the template itself needs to be dynamic (for example pluralization). That can be achieved using a function call:
// translation.js 'There are {catsCount} cats in this room.': { if catsCount === 1 return 'There is {catsCount} cat in this room.' return 'There are {catsCount} cats in this room.' } // ... // any component file<Translate ='There are {catsCount} cats in this room.' = /><Translate ='There are {catsCount} cats in this room.' = />
Renders as:
Since these templates are simple function calls, things more complex than pluralization can be done too:
// translation.js 'This is a {fruit}': { if /^[aeiou]/ return 'This is an {fruit}' return 'This is a {fruit}' } // ... // any component file<Translate ='This is a {fruit}' = /><Translate ='This is a {fruit}' = />
Renders as:
Styled text
The translated text can also have some basic styling applied:
// translation.js 'Hi, *World*!': en: 'Hi, *World*!' fr: 'Bonjour *le monde*!' // any component file<Translate ='Hi, *World*!' />
Renders as:
And of course the same can be done with dynamic templates:
// translation.js 'Hi, *{firstName}*!': en: 'Hi, *{firstName}*!' fr: 'Salut *{firstName}*!' // any component file<Translate ='Hi, *{firstName}*!' = />
Renders as:
Component within text
For more advanced uses where Markdown and Emojis don’t suffice, components can be rendered within the text:
// translation.js 'Tap the <StarIcon> to add': en: 'Tap the <StarIcon> to add' fr: 'Appuyez sur la <StarIcon> pour ajouter' // any component file<Translate ='Tap the <StarIcon> to add!' = />
Renders as:
Another practical application of this is nested translations - text that requires data that also needs to be translated:
// translation.js 'I was born in <MonthName>': en: 'I was born in <MonthName>' fr: 'Je suis né en <MonthName>' 'August': en: 'August' fr: 'août' // any component fileconst monthName = 'August'<Translate ='I was born in <MonthName>' = />
Renders as:
Translated text as string
Added v2.2.0
In scenarios where the translated text is required as a string, such as with text inputs placeholders or accessibility labels, the Translator
can be used:
// translation.js 'Enter your age {firstName}': en: 'Enter your age {firstName}' fr: 'entrez votre âge {firstName}' // any component file<Translator> translate <input = /> </Translator>
Renders as:
Contributors
amsul 💻 🎨 📖 💡 🔧 |
Johnson Su 🐛 💻 |
---|
👋 Interested becoming a contributor too?
Awesome! This project follows the all-contributors specification. Contributions of any kind are welcome!
You may also want to take a look at our TODOs below and make sure to give our Contributing guide a read.
TODOs
- Add tests using Jest
License
Licensed under MIT.
© 2019 Amsul