Documentation: Advanced usage

Advanced usage

English

Handling right-to-left languages

TacoTranslate makes it easy to support right-to-left (RTL) languages, such as Arabic and Hebrew, in your React applications. Proper handling of RTL languages ensures that your content is displayed correctly for users who read from right to left.

import {useTacoTranslate} from 'tacotranslate/react';

function Document() {
	const {locale, isRightToLeft} = useTacoTranslate();

	return (
		<html lang={locale} dir={isRightToLeft ? 'rtl' : 'ltr'}>
			<body>
				// ...
			</body>
		</html>
	);
}

You can also use the provided isRightToLeftLocaleCode function to check the current language outside of React.

import {isRightToLeftLocaleCode} from 'tacotranslate';

function foo(locale = 'es') {
	const direction = isRightToLeftLocaleCode(locale) ? 'rtl' : 'ltr';
	// ...
}

Disabling translation

To disable translation for specific parts of a string or to ensure certain segments are preserved as-is, you can use triple square brackets. This feature is useful for maintaining the original format of names, technical terms, or any other content that should not be translated.

import {Translate} from 'tacotranslate/react';

function Component() {
	return (
		<Translate string="Hello, [[[TacoTranslate]]]!" />
	);
}

In this example, the word “TacoTranslate” will remain unchanged in the translation.

Multiple TacoTranslate providers

We strongly encourage utilizing multiple TacoTranslate providers in your app. This is useful for organizing your translations and strings into different origins, such as your header, footer, or specific sections.

TacoTranslate providers inherit settings from any parent provider, so you won’t have to repeat any other settings.

import createTacoTranslateClient from 'tacotranslate';
import {TacoTranslate} from 'tacotranslate/react';

const tacoTranslateClient = createTacoTranslateClient({apiKey: 'YOUR_API_KEY'});

function Header() {
	return (
		<TacoTranslate origin="header">
			// ...
		</TacoTranslate>
	);
}

function Menu() {
	return (
		<TacoTranslate origin="menu">
			// ...
		</TacoTranslate>
	);
}

export default function App() {
	return (
		<TacoTranslate client={tacoTranslateClient} origin="page" locale="es">
			<Header />
			<Menu />
		</TacoTranslate>
	);
}

Overriding origin or locale

In addition to using multiple TacoTranslate providers, you can also override both origin and locale on the Translate component and useTranslation hook levels.

import {Translate, useTranslation} from 'tacotranslate/react';

function Greeting() {
	const spanishHello = useTranslation('Hello!', {locale: 'es'});

	return (
		<>
			{spanishHello}
			<Translate string="What’s up?" origin="greeting" />
		</>
	);
}

Handling loading

When changing languages on the client side, fetching translations might take a few moments depending on the user’s connection. You can display a loading indicator to enhance the user experience by providing visual feedback during the switch.

import {useTacoTranslate} from 'tacotranslate/react';

function Component() {
	const {isLoading} = useTacoTranslate();

	return (
		isLoading ? 'Translations are loading...' : null
	);
}

Pluralization

To handle pluralization and display count-based labels correctly in different languages, this is considered best practice:

import {Translate, useLocale} from 'tacotranslate/react';

function PhotoCount() {
	const locale = useLocale();
	const count = 1;

	return count === 0 ? (
		<Translate string="You have no photos." />
	) : count === 1 ? (
		<Translate string="You have 1 photo." />
	) : (
		<Translate
			string="You have {{count}} photos."
			variables={{count: count.toLocaleString(locale)}}
		/>
	);
}

Multiple languages

To support multiple languages simultaneously within the same application, you can use multiple TacoTranslate providers with different locale values as shown below:

You can also override the locale on the component or hook level.

import createTacoTranslateClient from 'tacotranslate';
import {TacoTranslate, Translate} from 'tacotranslate/react';

const tacoTranslateClient = createTacoTranslateClient({apiKey: 'YOUR_API_KEY'});

function Spanish() {
	return (
		<TacoTranslate locale="es">
			<Translate string="Hello, world in Spanish!" />
		</TacoTranslate>
	);
}

function Norwegian() {
	return (
		<TacoTranslate locale="no">
			<Translate string="Hello, world in Norwegian!" />
		</TacoTranslate>
	);
}

export default function App() {
	return (
		<TacoTranslate client={tacoTranslateClient} origin="page" locale="es">
			<Spanish />
			<Norwegian />
		</TacoTranslate>
	);
}

Using translation IDs

You can add an id to the Translate component to handle different translations or meanings for the same string. This is particularly useful when the same text requires different translations based on context. By assigning unique IDs, you ensure that each instance of the string is translated accurately according to its specific meaning.

import {Translate} from 'tacotranslate/react';

function Header() {
	return (
		<Translate id="header" string="Login" />
	);
}

function Footer() {
	return (
		<Translate id="footer" string="Login" />
	);
}

For example, header login might translate to “Iniciar sesión”, and footer login might translate to “Acceder” in Spanish.

Best practices