Documentação: Usando TacoTranslate

Usando o TacoTranslate

Portuguese (Brazil)

Traduzindo strings

Atualmente existem três maneiras de traduzir strings: o componente Translate, o hook useTranslation, ou a utilidade translateEntries.

Usando o componente Translate.
Exibe traduções dentro de um elemento span, e suporta a renderização de HTML.

import {Translate} from 'tacotranslate/react';

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

Você pode alterar o tipo do elemento usando, por exemplo, as="p" no componente.

Usando o hook useTranslation.
Retorna traduções como uma string simples. Útil, por exemplo, em tags meta.

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>
	);
}

Usando o utilitário translateEntries.
Traduza strings no lado do servidor. Potencialize suas imagens OpenGraph.

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)
	};
}

Como as strings são traduzidas

Quando as strings chegam aos nossos servidores, primeiro as validamos e as armazenamos e, em seguida, retornamos imediatamente uma tradução automática. Embora as traduções automáticas sejam geralmente de qualidade inferior às nossas traduções por IA, elas oferecem uma resposta inicial rápida.

Simultaneamente, iniciamos um trabalho de tradução assíncrono para gerar uma tradução por IA de alta qualidade e de ponta para sua string. Assim que a tradução por IA estiver pronta, ela substituirá a tradução automática e será enviada sempre que você solicitar traduções para suas strings.

Se você tiver traduzido manualmente uma string, essas traduções têm precedência e serão retornadas em seu lugar.

Utilizando origens

Projetos TacoTranslate contêm o que chamamos de origens. Pense nelas como pontos de entrada, pastas ou grupos para suas strings e traduções.

import {TacoTranslate} from 'tacotranslate/react';

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

As origens permitem que você separe strings em contêineres significativos. Por exemplo, você pode ter uma origem para a documentação e outra para a sua página de marketing.

Para um controle mais granular, você pode configurar origens no nível do componente.

Para isso, considere usar vários provedores TacoTranslate no seu projeto.

Observe que a mesma string pode receber traduções diferentes em origens diferentes.

Em última análise, a forma como você separa strings em origens depende de você e das suas necessidades. No entanto, observe que ter muitas strings em uma única origem pode aumentar o tempo de carregamento.

Manipulação de variáveis

Você deve sempre usar variáveis para conteúdo dinâmico, como nomes de usuário, datas, endereços de e-mail e muito mais.

As variáveis em strings são declaradas usando chaves duplas, como {{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}});
}

Gerenciando conteúdo HTML

Por padrão, o componente Translate suporta e renderiza conteúdo HTML. No entanto, você pode optar por não usar esse comportamento definindo useDangerouslySetInnerHTML como false.

Recomenda-se fortemente desativar a renderização de HTML ao traduzir conteúdo não confiável, como conteúdo gerado por usuários.

Todas as saídas são sempre sanitizadas com sanitize-html antes de serem renderizadas.

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}
		/>
	);
}

O exemplo acima será renderizado como texto simples.

Renderização do lado do servidor