Documentação: Usar o TacoTranslate

Utilizar o TacoTranslate

Portuguese (Portugal)

Tradução de strings

Atualmente existem três formas de traduzir strings: o componente Translate, o hook useTranslation, ou o utilitário translateEntries.

Utilizar 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!" />;
}

Pode alterar o tipo de elemento usando, por exemplo, as="p" no componente.

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

Utilizar o utilitário translateEntries.
Traduza cadeias de texto no servidor. Potencie as 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 cadeias de texto chegam aos nossos servidores, primeiro as validamos e as guardamos, e de imediato devolvemos uma tradução automática. Embora as traduções automáticas sejam, em geral, de qualidade inferior às nossas traduções por IA, fornecem uma resposta inicial rápida.

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

Se traduziu manualmente uma string, essas traduções têm prioridade e são utilizadas em seu lugar.

Utilização de origens

Os projetos TacoTranslate contêm aquilo a que chamamos origins. Pense neles como pontos de entrada, pastas ou grupos para as suas strings e traduções.

import {TacoTranslate} from 'tacotranslate/react';

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

Origins permitem que separe strings em contentores significativos. Por exemplo, pode ter um origin para a documentação e outro para a sua página de marketing.

Para um controlo mais granular, poderia configurar origens ao nível do componente.

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

Tenha em atenção que a mesma string pode ter traduções diferentes em origens distintas.

Em última análise, a forma como separa as strings em origens depende de si e das suas necessidades. No entanto, tenha em atenção que ter muitas strings numa única origem pode aumentar os tempos de carregamento.

Manipulação de variáveis

Deve sempre usar variáveis para conteúdo dinâmico, como nomes de utilizador, 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}});
}

Gestão de conteúdo HTML

Por predefinição, o componente Translate suporta e apresenta conteúdo HTML. No entanto, pode desativar este comportamento definindo useDangerouslySetInnerHTML como false.

Recomenda-se vivamente desativar a renderização HTML ao traduzir conteúdo não fiável, como conteúdo gerado pelos utilizadores.

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á apresentado como texto simples.

Renderização do lado do servidor