Documentation: Using TacoTranslate

Using TacoTranslate

English

Translating strings

There are currently three ways to translate strings: The Translate component, the useTranslation hook, or the translateEntries utility.

Using the Translate component.
Outputs translations within a span element, and supports rendering HTML.

import {Translate} from 'tacotranslate/react';

function Page() {
	return <Translate string="Hello, world!" />;
}

You can change the element type using, for example, as="p" on the component.

Using the useTranslation hook.
Returns translations as a plain string. Useful in, for example, meta tags.

import {useEffect} from 'react';
import {useTranslation} from 'tacotranslate/react';

function Page() {
	const helloWorld = useTranslation('Hello, world!');

	useEffect(() => {
		alert(helloWorld);
	}, [helloWorld]);

	return (
		<title>{useTranslation('My page title')}</title>
	);
}

Using the translateEntries utility.
Translate strings on the server side. Supercharge your OpenGraph images.

import {createEntry, translateEntries} from 'tacotranslate';

async function generateMetadata(locale = 'es') {
	const title = createEntry({string: 'Hello, world!'});
	const description = createEntry({string: 'TacoTranslate on the server'});

	const translations = await translateEntries(
		tacoTranslate,
		{origin: 'opengraph', locale},
		[title, description]
	);

	return {
		title: translations(title),
		description: translations(description)
	};
}

When strings reach our servers, we first validate and save them, then immediately return a machine translation. While machine translations are generally lower in quality compared to our AI translations, they provide a quick initial response.

Simultaneously, we initiate an asynchronous translation job to generate a high-quality, state-of-the-art AI translation for your string. Once the AI translation is ready, it will replace the machine translation and be sent whenever you request translations for your strings.

If you have manually translated a string, those translations take precedence and are returned instead.

Utilizing origins

TacoTranslate projects contain what we call origins. Think of them as entry points, folders, or groups for your strings and translations.

import {TacoTranslate} from 'tacotranslate/react';

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

Origins let you separate strings into meaningful containers. For example, you could have one origin for documentation and another for your marketing page.

For more granular control, you could set up origins on the component level.

To achieve this, consider using multiple TacoTranslate providers within your project.

Please note that the same string may receive different translations in different origins.

Ultimately, how you separate strings into origins is up to you and your needs. However, note that having many strings within one origin may increase loading times.

Handling variables

You should always use variables for dynamic content, such as user names, dates, e-mail addresses, and more.

Variables in strings are declared using double brackets, like {{variable}}.

import {Translate} from 'tacotranslate/react';

function Greeting() {
	const name = 'Juan';
	return <Translate string="Hello, {{name}}!" variables={{name}} />;
}

import {useTranslation} from 'tacotranslate/react';

function useGreeting() {
	const name = 'Juan';
	return useTranslation('Hello, {{name}}!', {variables: {name}});
}

Managing HTML content

By default, the Translate component supports and renders HTML content. However, you can opt out of this behavior by setting useDangerouslySetInnerHTML to false.

Disabling HTML rendering is strongly recommended when translating untrusted content, such as user-generated content.

All output is always sanitized with sanitize-html before being rendered.

import {Translate} from 'tacotranslate/react';

function Page() {
	return (
		<Translate
			string={`
				Welcome to <strong>my</strong> website.
				I’m using <a href="{{url}}">TacoTranslate</a> to translate text.
			`}
			variables={{url: 'https://tacotranslate.com'}}
			useDangerouslySetInnerHTML={false}
		/>
	);
}

The above example will be rendered as plain text.

Server-side rendering

Using TacoTranslate

How strings are translated

Utilizing origins

Handling variables

Managing HTML content