@morningtrain/react-translations

React Translations

This package is heavily inspired by the translation features in Laravel and enables the use of the backend translation files in React.

The internal translation libraries in this package mirrors the PHP classes underlying Laravel's translation system.

View the documentation at Laravel for extra details.

Components

Translation

This is the primary component for displaying a translation.

<Translation 

  /* Prop specifying the path to the translation */
  name={'path.to.translation'}
  
  /* Set this prop to work with pluralized translations */
  count={2}
  
  /* Any parameters to replace in the translation string */
  data={{some: 'data'}}
  
  /* Use this value in case the target translation does not exist */
  defaultValue={'Display this if trans is missing'}
  
/>

DecodedTranslation

The DecodedTranslation component is similar to Translation, but it supports having HTML in the translation.

---

IMPORTANT:

This component uses dangerouslySetInnerHTML - see React Docs.

This component makes it possible to use highlighting as part of the translation string.

It means that [highlighted text], [[more highlighted text]], [[[very highlighted text]]] and [[[[extremly highlighted text]]]] in the translation are replaces with spans like this:

[[[[text]]]] -> <span class="text-highlight-4 >text</span>

[[[text]]] -> <span class="text-highlight-3 >text</span>

[[text]] -> <span class="text-highlight-2" >text</span>

[text] -> <span class="text-highlight-1" >text</span>

These spans can then be styled to have certain words in the translation stand out more.

Translator

Before using a Translation, it is important to make sure that Translation, DecodedTranslation or the component using any of the hooks are wrapped in the Translator component.

Translator provides translation helpers functions and makes it possible to namespace the translation.

When a translation is namespaced, it is possible to leave out the first part of the path.

It means that this example:

<Translator>
  <Translation name={'users.path.to.trans'} />
  <Translation name={'users.path.to.another_trans'} />
  <Translation name={'companies.road.to.third_trans'} />
</Translator>

Gives the same result as this where users.path.to becomes the namespace.

<Translator namespace={'users.path.to'}>
  <Translation name={'trans'} />
  <Translation name={'another_trans'} />
  <Translation name={'companies.road.to.third_trans'} />
</Translator>

Note how companies.road.to.third_trans is unchanged. If the translator is unable to find a matching translation key in the namespace, then it will search for the translation as if the provided path is without a namespace.

This means that it is possible to have global translation keys mixed in together with the namespaced translation keys.

Hooks

useTranslation

The useTranslation hook takes 3 parameters, name, options and defaultValue.

Note that both the Translation and DecodedTranslation components are using this hook internally. The translation components should always be used over the hook whenever possible.

It is okay to use the hook when the translation is needed as a string - for instance when passing it to an input field as a placeholder.

Name is the path to the translation.

Options contains count and data.

DefaultValue is the value to use when the translation key is not found.