Transifex Native is a full end-to-end, cloud-based localization stack for moderns apps.

Transifex Native SDK: React i18n

React component for localizing React application using
Transifex Native.

Related packages:
- @transifex/native
- @transifex/cli

Learn more about Transifex Native in the Transifex Developer Hub.

How it works

Step1: Create a Transifex Native project in Transifex.

Step2: Grab credentials.

Step3: Internationalize the code using the SDK.

Step4: Push source phrases using the @transifex/cli tool.

Step5: Translate the app using over-the-air updates.

No translation files required.

!native

Upgrade to v2

If you are upgrading from the 1.x.x version, please read this migration guide, as there are breaking changes in place.

Install

Install the library and its dependencies using:

``sh
npm install @transifex/native @transifex/react --save
`

Usage

T Component

`javascript
import React from 'react';

import { T } from '@transifex/react';

function Example() {
return (


);
}

`

Available optional props:

| Prop | Type | Description |
|------------|--------|---------------------------------------------|
| _context | String | String context, affects key generation |
| _key | String | Custom string key |
| _comment | String | Developer comment |
| _charlimit | Number | Character limit instruction for translators |
| _tags | String | Comma separated list of tags |

The T-component can accept React elements as properties and they will be
rendered properly, ie this would be possible:

`javascript
_str="A {button} and a {bold} walk into a bar"
button={}
bold={} />
`

This will render like this in English:

`html
A button and a bold walk into a bar
`

And like this in Greek:

`html
Ένα κουμπί και ένα βαρύ μπαίνουν σε ένα μπαρ
`

Assuming the translations look like this:

| source | translation |
|-----------------------------------------|--------------------------------------------------|
| A {button} and a {bold} walk into a bar | Ένα {button} και ένα {bold} μπαίνουν σε ένα μπαρ |
| button | κουμπί |
| bold | βαρύ |

The main thing to keep in mind is that the _str property to the T-component
must always be a valid ICU messageformat template.

UT Component

`javascript
import React from 'react';

import { UT } from '@transifex/react';

function Example () {
return (



)
}
`

UT has the same behaviour as T, but renders source string as HTML inside a
div tag.

Available optional props: All the options of T plus:

| Prop | Type | Description |
|---------|---------|-------------------------------------------------|
| _inline | Boolean | Wrap translation in span |

_Note: If you supply React elements as properties to the UT component, it
will misbehave by rendering [object Object]. Only use React elements as
properties with the T component._

useT hook

Makes the current component re-render when a language change is detected and
returns a t-function you can use to translate strings programmatically.

You will most likely prefer to use the T or UT components over this, unless
for some reason you want to have the translation output in a variable for
manipulation.

`javascript
import React from 'react';

import { useT } from '@transifex/react';

function Capitalized() {
const t = useT();
const message = t('Hello world');
return {message.toUpperCase()};
}
`

Optionally useT can take as param a custom Native Instance:

`javascript
import { useT } from '@transifex/react';
import { createNativeInstance } from '@transifex/native';

const customTX = createNativeInstance({
token: 'token',
secret: 'secret',
});

function Component() {
const t = useT(customTX);
// ...
}
`

useLanguages hook

Returns a state variable that will eventually hold the supported languages of
the application. Makes an asynchronous call to the CDS.

`jsx
import React from 'react';
import { useLanguages } from '@transifex/react';

function LanguageList () {
const languages = useLanguages();
return (


{languages.map(({ code, name }) => (

• 
  {code}: {name}
  

))}


);
}
`

Optionally useLanguages can take as param a custom Native Instance:

`javascript
import { useT } from '@transifex/react';
import { createNativeInstance } from '@transifex/native';

const customTX = createNativeInstance({
token: 'token',
secret: 'secret',
});

function Component() {
const languages = useLanguages(customTX);
// ...
}
`

useLocale hook

Returns a state variable with the currently selected locale.

`jsx
import React from 'react';
import { useLocale } from '@transifex/react';

function DisplayLocale () {
const locale = useLocale();
return (


Currently selected locale is {locale}


);
}
`

Optionally useLocale can take as param a custom Native Instance:

`javascript
import { useT } from '@transifex/react';
import { createNativeInstance } from '@transifex/native';

const customTX = createNativeInstance({
token: 'token',
secret: 'secret',
});

function Component() {
const locale = useLocale(customTX);
// ...
}
`

useTX hook

Returns a state variable with the Native instance.

`jsx
import React from 'react';
import { useTX } from '@transifex/react';

function SetLocale () {
const tx = useTX();
return (
tx.setCurrentLocale('el')}>
Set to Greek

);
}
`

LanguagePicker component

Renders a tag that displays supported languages and switches the
application's selected language on change.
Uses useLanguages and useLocale internally.

`jsx
import React from 'react';
import { T, LanguagePicker } from '@transifex/react';

function App () {
return (








);
}
`

Accepts properties:

- className: The CSS class that will be applied to the

tag

If you want something different than a , it should be easy to write
your own language picker using useLanguages:

`jsx
import React from 'react';
import { tx } from '@transifex/native';
import { useLanguages, useLocale } from '@transifex/react';

function MyLanguagePicker () {
const languages = useLanguages();
const locale = useLocale();

return (
<>
{languages.map(({ code, name }) => (
tx.setCurrentLocale(code)}>
{name} {locale === code ? '(selected)' : ''}

))}

);
}
`

useTranslations hook - aka Lazy Loading

Fetches translations tagged with a specific combination of tags when a
component first renders. This way, you can pull translations from the CDS in
batches and only when needed:

`jsx
tx.init({ token: ..., filterTags: 'home' });

export default function App() {
return (
<>

{someCondition() && }

);
}

function Inner() {
useTranslations('inner');
return _str="This will be translated when the inner component is rendered"
_tags="inner" />;
}
`

The hook returns a boolean state variable called ready that you can use to
handle a loading state:

`jsx
function Inner() {
const { ready } = useTranslations('inner');
if (!ready) { return 'Loading...'; }
return _str="This will be translated when the inner component is rendered"
_tags="inner" />;
}
`

_If you don't handle the loading state, the source string will be rendered
first and then replaced with the translation when it becomes available._

You can also use the hook in parent components that don't need the tagged
translations themselves. This will make the translations available sooner for
child components that may potentially need them:

`jsx
tx.init({ token: ..., filterTags: 'home' });

export default function App() {
const { ready: innerReady } = useTranslations('inner');
return (
<>

{someCondition() && }

);
}

function Inner({ ready }) {
if (!ready) { return 'Loading...'; }
return _str="This will be translated when the inner component is rendered"
_tags="inner" />;
}
`

Optionally useTranslations can take as a second param a custom Native Instance:

`javascript
import { useT } from '@transifex/react';
import { createNativeInstance } from '@transifex/native';

const customTX = createNativeInstance({
token: 'token',
secret: 'secret',
});

function Component() {
const { ready } = useTranslations('inner', customTX);
// ...
}
`

TXProvider provider

If you need to use more than one Transifex Native instances - like for example if you have a component library - you can use this provider to pass the desired instance to the children components.

`js
import { tx, createNativeInstance } from '@transifex/native';
import { TXProvider, LanguagePicker, T } from '@transifex/react';

const myOtherTXInstance = createNativeInstance();
myOtherTXInstance.init({ token: 'othertoken' })

tx.init({
token: 'token',
});

// Make tx aware of the other instances so they can be synced when changing
// language
tx.controllerOf(myOtherTXInstance);

export default function App() {
return (
<>






);
}
``

License

Licensed under Apache License 2.0, see LICENSE file.

Show more